@garethdaine/agentops 0.9.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "agentops",
+  "version": "0.9.0",
+  "description": "Enterprise guardrails, delivery lifecycle, and self-evolution for Claude Code CLI",
+  "author": { "name": "Gareth Daine", "email": "1745959+garethdaine@users.noreply.github.com" },
+  "homepage": "https://github.com/garethdaine/agentops",
+  "repository": "https://github.com/garethdaine/agentops",
+  "license": "MIT",
+  "keywords": ["guardrails", "security", "planning", "compliance", "audit", "telemetry", "tdd", "delivery", "enterprise"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Daine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,410 @@
+# AgentOps — Enterprise Guardrails & Delivery Lifecycle for Claude Code
+
+A plugin for [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) that wraps every session in 7 security layers, structures work with the STAR methodology, auto-pilots workflows, delegates to 12 specialist agents, learns from failures via self-evolution, and orchestrates full project builds from vision to merged PR.
+
+37 slash commands | 44 hooks | 12 specialist agents | 49 templates | 32+ feature flags
+
+**License:** MIT | **Version:** 0.9.0
+
+---
+
+## Quick Start
+
+### Install via npm
+
+```bash
+npm install -g @garethdaine/agentops
+
+# Run Claude Code with the plugin loaded
+claude --plugin-dir $(npm root -g)/@garethdaine/agentops
+```
+
+### Or clone from GitHub
+
+```bash
+git clone https://github.com/garethdaine/agentops.git agentops-plugin
+
+claude --plugin-dir ./agentops-plugin
+```
+
+On first session, the plugin auto-initializes `.agentops/` with default flags and budget.
+
+---
+
+## AgentOps vs GSD vs Superpowers
+
+| Dimension | AgentOps | GSD (~31K stars) | Superpowers (~50K stars) |
+|-----------|----------|-------------------|--------------------------|
+| **Core identity** | Enterprise guardrailing + full delivery lifecycle | Spec-driven meta-prompting to beat context rot | Skills-based methodology with TDD enforcement |
+| **Commands** | 37 | ~15 | ~10 (skill-based) |
+| **Hooks** | 44 shell scripts across 7 lifecycle events | None (prompts only) | None (prompts only) |
+| **Agents** | 12 specialist agents | 4 parallel researchers + planner | Code reviewer agent |
+| **Security** | 7 layers (injection, exfiltration, supply-chain, Unicode, credential, path, env) | Minimal | None |
+| **Self-evolution** | EvoSkill (failures → proposer → skill-builder → feedback loop) | KNOWLEDGE.md (manual) | Skill extraction (manual) |
+| **TDD enforcement** | Mandatory RED→GREEN→REFACTOR + Nyquist rule (`<test>`/`<verify>`/`<done>` on every task); auto-test hook in sessions | Nyquist rule (verify required) | Code without tests = deleted |
+| **Context strategy** | Fresh subagent per task (build_fresh_context) + session hooks | Fresh 200K context per subagent | Fresh context per subagent |
+| **Parallel execution** | Wave-based with dependency graphs + 4 parallel researchers | Wave-based parallel execution | N/A |
+| **Persuasion psychology** | 5 Cialdini techniques embedded in human gates | None | 5 Cialdini techniques |
+| **Plan format** | STAR markdown + XML with Nyquist compliance (<test>/<verify>/<done>) | XML executable plans | Markdown plans |
+| **Git workflow** | Configurable strategy (worktree / feature-branch / trunk-based); atomic commits per task, conventional commit format | Atomic commits, worktrees | Worktrees, atomic commits |
+| **Review** | Two-stage: spec compliance (requirements mapping) + code quality (11 dimensions) | N/A | Two-stage review |
+| **Feature flags** | 32+ independently toggleable with presets | Minimal settings | None |
+| **Enterprise templates** | 49 templates (discovery → delivery → handover) | None | None |
+| **Observability** | Audit logs, OTLP telemetry, file provenance, cost budgets | None | None |
+| **Configurable autonomy** | guided / supervised / autonomous | N/A | N/A |
+| **Linear integration** | Task sync (create, status update, close) | None | None |
+
+### What AgentOps does that neither competitor does
+
+1. **7-layer security system.** Injection scanning, exfiltration detection, Unicode/Glassworm defense, path traversal protection, credential redaction, env var guarding, and content trust — all running as hooks on every tool invocation.
+2. **EvoSkill self-evolution.** The failure-collector → proposer → skill-builder → feedback-history pipeline auto-generates skills from failures. No manual intervention.
+3. **Full observability.** Structured audit logs, OTLP telemetry export, file provenance tracking, and cost budgets with session-level granularity.
+4. **8.5-phase build lifecycle.** From brainstorm to merged PR with state machine, resumability, human gates, parallel research, TDD enforcement, two-stage review, and Nyquist verification — all configurable via feature flags and autonomy levels.
+
+---
+
+## Architecture
+
+The plugin integrates through four extension points:
+
+| Extension Point | Location | Count | Purpose |
+|-----------------|----------|-------|---------|
+| **Hooks** | `hooks/hooks.json` | 44 | Intercept tool use at every lifecycle event |
+| **Commands** | `commands/*.md` | 37 | User-facing slash commands (`/agentops:*`) |
+| **Agents** | `agents/*.md` | 12 | Specialist subagents for analysis and execution |
+| **Templates** | `templates/**/*.md` | 49 | Standards, architecture patterns, delivery docs |
+
+Runtime state lives in `.agentops/` (auto-created, gitignored).
+
+---
+
+## The Build Command
+
+`/agentops:build` is the master lifecycle command — it orchestrates a project from raw vision to merged, verified code.
+
+### 8.5 Phases
+
+| Phase | Name | What happens | Human gate? |
+|-------|------|-------------|-------------|
+| 1 | **BRAINSTORM** | Vision capture → 3 alternative framings → brief | Yes |
+| 2 | **INTERROGATION** | 4 parallel researchers + exhaustive Q&A → requirements | Yes |
+| 3 | **PLANNING** | STAR analysis → XML plan → 8-dimension validation | Yes |
+| 4 | **TASK BREAKDOWN** | Parse XML → per-task TDD mini-plans → Linear sync | Yes |
+| 4.5 | **SCAFFOLD** | Auto-scaffold new projects (conditional) | — |
+| 5 | **EXECUTION** | Fresh subagent per task, wave-based parallelism, TDD enforced | Supervised only |
+| 6 | **REVIEW** | Stage 1: spec compliance → Stage 2: code quality → fix wave | Yes |
+| 7 | **VERIFICATION** | Nyquist audit + full test suite + E2E + compliance gates | Yes |
+| 8 | **APPROVAL** | Summary → PR creation → Linear cleanup → lesson capture | Yes |
+
+### Key features
+
+- **Resumable state machine** — state saved to `.agentops/build-state.json` after each phase
+- **Fresh context per task** — each execution task gets a fresh 200K-token subagent with full standards injection
+- **Mandatory TDD** — RED→GREEN→REFACTOR enforced; no code without a failing test first
+- **Nyquist compliance** — every task must have `<test>`, `<verify>`, and `<done>` in the XML plan
+- **4 parallel researchers** — stack, architecture, features, pitfalls research runs concurrently
+- **8-dimension plan validation** — completeness, dependency DAG, file ownership, task size, Nyquist, wave ordering, TDD ordering, commit quality
+- **Two-stage review** — spec compliance reviewer maps every requirement to implementation; code quality reviewer checks 11 dimensions
+- **Persuasion psychology** — Cialdini's 5 techniques (authority, commitment, scarcity, social proof, loss aversion) embedded in human gates
+- **Quick mode** — `--quick` for brainstorm → plan → execute → verify (no interrogation, no PR)
+
+---
+
+## Security (7 Layers)
+
+| Layer | Hook | What it blocks |
+|-------|------|---------------|
+| Command validation | `validate-command.sh` | `rm -rf /`, fork bombs, shell injection, destructive ops |
+| Path validation | `validate-path.sh` | Path traversal, system dirs, sensitive dotfiles |
+| Env protection | `validate-env.sh` | `PATH`/`HOME` reassignment, credential patterns |
+| Injection detection | `injection-scan.sh` | Role-switching, authority markers, delimiter attacks |
+| Exfiltration prevention | `exfiltration-check.sh` | `curl`/`wget` with sensitive files, base64+network combos |
+| Credential redaction | `credential-redact.sh` | `.env`, `.pem`, `.key` access → audit + alert |
+| Content trust | `content-trust.sh` | Flags external content as untrusted + optional LLM firewall |
+
+Plus supply-chain defense: Unicode/Glassworm detection (`unicode-firewall.sh`), integrity verification (`integrity-verify.sh`), and lockfile auditing (`lockfile-audit.sh`).
+
+---
+
+## Commands (37)
+
+### Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/agentops:build` | Master 8.5-phase project lifecycle — vision to merged PR |
+| `/agentops:plan` | STAR-based implementation plan with checkable tasks |
+| `/agentops:star` | Quick STAR analysis (lighter than plan) |
+| `/agentops:interrogate` | Exhaustive requirements discovery — eliminates all assumptions |
+| `/agentops:workflow` | 8-phase workflow mapping with YAML schemas and Mermaid diagrams |
+| `/agentops:verify` | Verify task completion against STAR criteria |
+| `/agentops:evolve` | Run EvoSkill self-improvement loop |
+| `/agentops:code-field` | Code Field methodology (decompose, solve with confidence, verify) |
+| `/agentops:code-analysis` | Structured code analysis on current project |
+| `/agentops:lessons` | Display all captured lessons |
+| `/agentops:lesson` | Capture a single lesson learned |
+| `/agentops:compliance-check` | Run compliance gates manually |
+| `/agentops:cost-report` | Session cost tracking and budget status |
+| `/agentops:flags` | View or toggle feature flags |
+| `/agentops:configure` | Unified configuration interface with presets |
+| `/agentops:prune` | Clean up stale runtime state |
+| `/agentops:supply-chain-scan` | Scan dependencies for supply-chain threats |
+| `/agentops:unicode-scan` | Scan project for invisible Unicode characters |
+
+### Enterprise Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/agentops:feature` | 6-phase structured feature build with configurable autonomy |
+| `/agentops:scaffold` | Interactive project scaffolding with tech stack selection |
+| `/agentops:review` | Unified code review (code-critic + security-reviewer agents) |
+| `/agentops:test-gen` | AI-generated test suites with quality validation |
+| `/agentops:reason` | Multi-step reasoning: Analyse → Design → Validate → Recommend |
+| `/agentops:design` | Solution design — architecture proposals, risk assessment |
+| `/agentops:adr` | Architecture Decision Records |
+| `/agentops:brainstorm` | Structured brainstorming sessions |
+| `/agentops:qa-check` | Pre-deployment QA: security, performance, accessibility |
+| `/agentops:handover` | Client handover documentation and runbooks |
+| `/agentops:onboard` | Generate onboarding guides from project structure |
+| `/agentops:knowledge` | Search project knowledge base |
+| `/agentops:status-report` | Client-facing status report from git history |
+| `/agentops:tech-catalog` | Technology catalog and stack documentation |
+| `/agentops:gap-analysis` | Gap analysis between current and desired state |
+| `/agentops:dev-setup` | Developer environment setup guide |
+| `/agentops:docker-dev` | Docker development environment configuration |
+| `/agentops:e2e` | End-to-end test planning and execution |
+| `/agentops:herd` | Multi-agent coordination for complex tasks |
+
+---
+
+## Specialist Agents (12)
+
+### Core Agents
+
+| Agent | Tools | Purpose |
+|-------|-------|---------|
+| `code-critic` | Read, Grep, Glob, Bash | 11-dimension code quality review |
+| `security-reviewer` | Read, Grep, Glob, Bash, WebSearch | OWASP Top 10, CVE scanning, auth gaps |
+| `interrogator` | Read, Grep, Glob, WebSearch | Requirements discovery and plan generation |
+| `proposer` | Read, Grep, Glob | Failure analysis → skill proposals (EvoSkill) |
+| `skill-builder` | Read, Grep, Glob, Bash | Materialize skill proposals into SKILL.md files |
+| `delegation-router` | Read, Grep, Glob | Route tasks to appropriate specialist agents |
+
+### Build Agents (Phase-specific)
+
+| Agent | Phase | Tools | Purpose |
+|-------|-------|-------|---------|
+| `stack-researcher` | 2 | Read, Grep, Glob, WebSearch | Technology stack options with fit scores |
+| `architecture-researcher` | 2 | Read, Grep, Glob, WebSearch | Architectural patterns and ADRs |
+| `feature-researcher` | 2 | Read, Grep, Glob, WebSearch | MVP vs v2 scope, feature trade-offs |
+| `pitfalls-researcher` | 2 | Read, Grep, Glob, WebSearch | Anti-patterns, failure modes, security pitfalls |
+| `plan-validator` | 3 | Read, Grep, Glob | 8-dimension plan validation |
+| `spec-compliance-reviewer` | 6 | Read, Grep, Glob, Bash | Requirement mapping + standards compliance |
+
+---
+
+## Hook System (44 hooks)
+
+Hooks fire at 7 lifecycle events:
+
+| Event | When | Example hooks |
+|-------|------|---------------|
+| `SessionStart` | Session begins | session-cleanup, star-preamble, code-field-preamble, lessons-check, budget-check, unicode-scan, integrity-verify, lockfile-audit |
+| `PreToolUse` | Before tool executes | validate-command, validate-path, validate-env, injection-scan, exfiltration-check, star-gate, auto-plan, runtime-mode |
+| `PostToolUse` | After tool completes | content-trust, unicode-firewall, integrity-verify, credential-redact, detect-test-run, standards-enforce, ai-guardrails, plan-gate, auto-test, auto-delegate, audit-log, telemetry |
+| `PostToolUseFailure` | After tool fails | failure-collector, auto-lesson, evolve-gate, telemetry |
+| `SubagentStart` | Subagent spawned | delegation-trust |
+| `Stop` | Session ending | auto-verify, auto-evolve, compliance-gate |
+| `SessionEnd` | Final cleanup | telemetry |
+
+---
+
+## EvoSkill Self-Evolution
+
+```
+Tool Failure → failure-collector.sh → failures.jsonl
+                                          ↓
+                                    /agentops:evolve
+                                          ↓
+                              proposer agent (analyze failures,
+                              check existing skills & feedback)
+                                          ↓
+                                    Skill Proposal
+                                          ↓
+                              skill-builder agent (materialize SKILL.md)
+                                          ↓
+                              feedback-history.jsonl (record outcome)
+```
+
+Triggered automatically at session stop (if 2+ unprocessed failures exist) or manually via `/agentops:evolve`.
+
+---
+
+## Engineering Standards
+
+The build system injects comprehensive engineering standards into every execution subagent:
+
+- **SOLID** — all 5 principles with heuristics and code examples (SRP: ≤30 line functions, ≤200 line classes)
+- **Clean Code** — naming, functions (≤3 params, command-query separation), error handling (typed hierarchy, correlation IDs)
+- **DRY/KISS/YAGNI** — with clear thresholds (2+ locations = extract, 3+ uses before abstracting)
+- **Design Patterns** — creational, structural, behavioral with selection heuristic ("name the problem it solves")
+- **Action-Based Architecture** — single-purpose action classes for business logic
+- **DDD** — aggregates, entities, value objects, domain services, ubiquitous language
+- **Layered Architecture** — controller → service → domain → repository (no skipping, violations = CRITICAL)
+- **Security** — injection prevention, secrets management, auth, input validation, data protection (all CRITICAL)
+- **Testing** — Arrange-Act-Assert, red-first TDD, behaviour over implementation
+
+Standards are enforced via `templates/standards/standards-checklist.md` during Phase 6 review.
+
+---
+
+## Feature Flags (32+)
+
+All flags default to sensible values and are toggleable via `/agentops:flags` or `.agentops/flags.json`.
+
+### Security flags
+`command_validation_enabled`, `path_validation_enabled`, `env_validation_enabled`, `injection_scan_enabled`, `content_trust_enabled`, `exfiltration_detection_enabled`, `credential_redaction_enabled`, `llm_content_firewall_enabled`
+
+### Workflow flags
+`star_preamble_enabled`, `code_field_rules_enabled`, `plan_gate_enabled`, `verification_gate_enabled`, `test_gate_enabled`, `lessons_enabled`
+
+### Automation flags
+`auto_plan_enabled`, `auto_test_enabled`, `auto_verify_enabled`, `auto_lesson_enabled`, `auto_evolve_enabled`, `auto_delegate_enabled`
+
+### Build lifecycle flags
+`build_tdd_enforced`, `build_parallel_research`, `build_xml_plans`, `build_linear_sync`, `build_fresh_context`, `build_wave_parallel`, `build_nyquist_enforce`, `build_persuasion`, `build_quick_mode`, `build_scaffold_auto`, `build_standards_inject`, `standards_enforcement_mode`
+
+### Enterprise flags
+`enterprise_scaffold`, `ai_workflows`, `unified_review`, `architecture_guardrails`, `delivery_lifecycle`, `team_governance`, `client_comms`
+
+### Autonomy levels
+- **guided** (default) — all human gates active
+- **supervised** — all human gates + step-level confirmation during execution
+- **autonomous** — skip soft gates, only hard security gates remain
+
+### Configuration presets
+```bash
+/agentops:configure preset minimal      # Security only, no automation
+/agentops:configure preset standard     # Security + core automation
+/agentops:configure preset enterprise   # All features, guided autonomy
+/agentops:configure preset autonomous   # All features, minimal gates
+```
+
+---
+
+## Observability
+
+| System | File | Purpose |
+|--------|------|---------|
+| Audit log | `.agentops/audit.jsonl` | Every tool invocation with timestamp, session, tool, input |
+| Telemetry | `.agentops/telemetry.jsonl` | Structured events with optional OTLP export |
+| File provenance | `.agentops/provenance.jsonl` | Source and trust level of every file interaction |
+| Cost tracking | `.agentops/budget.json` | Session budget with 80% warning threshold |
+| Build execution | `.agentops/build-execution.jsonl` | Per-task execution log with TDD phase tracking |
+| Failure log | `.agentops/failures.jsonl` | Tool failures for EvoSkill analysis |
+| Integrity | `.agentops/integrity.jsonl` | SHA-256 manifest of agent-written files |
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AGENTOPS_MODE` | `standard` | Runtime mode (`safe`, `standard`, `full`, `unrestricted`) |
+| `AGENTOPS_BUDGET_USD` | `5` | Session cost budget in USD |
+| `OTLP_ENDPOINT` | _(none)_ | OpenTelemetry endpoint for telemetry forwarding |
+| `LINEAR_API_KEY` | _(none)_ | Linear API key for build task sync |
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `.claude-plugin/plugin.json` | Plugin metadata |
+| `hooks/hooks.json` | Master hook registry |
+| `settings.json` | Plugin permission defaults |
+| `.agentops/flags.json` | Feature flag toggles (auto-created) |
+| `.agentops/budget.json` | Cost tracking (auto-created) |
+
+---
+
+## Directory Structure
+
+```
+agentops-plugin/
+├── .claude-plugin/
+│   └── plugin.json                 # Plugin metadata
+├── hooks/                          # 44 shell scripts + hooks.json
+│   ├── hooks.json                  # Master hook registry
+│   ├── feature-flags.sh            # Shared flag library (facade)
+│   ├── flag-utils.sh               # Core flag reading
+│   ├── enforcement-lib.sh          # Enforcement actions
+│   ├── patterns-lib.sh             # Shared patterns & thresholds
+│   ├── redact-lib.sh               # Secret redaction
+│   ├── evolve-lib.sh               # Failure tracking helpers
+│   ├── unicode-lib.sh              # Unicode detection library
+│   └── *.sh                        # Security, automation, compliance hooks
+├── commands/                       # 37 slash commands
+│   ├── build.md                    # /agentops:build (master lifecycle)
+│   ├── plan.md                     # /agentops:plan (STAR planning)
+│   ├── interrogate.md              # /agentops:interrogate (requirements)
+│   ├── workflow.md                 # /agentops:workflow (process mapping)
+│   └── enterprise/                 # 19 enterprise delivery commands
+├── agents/                         # 12 specialist agents
+│   ├── code-critic.md              # Code quality (11 dimensions)
+│   ├── security-reviewer.md        # Security (OWASP, CVEs)
+│   ├── stack-researcher.md         # Technology research (build Phase 2)
+│   ├── architecture-researcher.md  # Architecture research (build Phase 2)
+│   ├── feature-researcher.md       # Feature scoping (build Phase 2)
+│   ├── pitfalls-researcher.md      # Failure modes (build Phase 2)
+│   ├── plan-validator.md           # 8-dimension validation (build Phase 3)
+│   └── spec-compliance-reviewer.md # Spec + standards review (build Phase 6)
+├── templates/                      # 49 templates
+│   ├── standards/                  # Engineering standards + checklist
+│   ├── build/                      # Brief, task-plan, summary templates
+│   ├── architecture/               # 8 architecture pattern templates
+│   ├── delivery/                   # Discovery → deployment → handover
+│   ├── communication/              # Stakeholder comms templates
+│   ├── workflows/                  # Feature, refactor, spike, bug workflows
+│   └── scaffolds/                  # Error handling, logging, health checks
+├── tests/                          # BATS test suite
+├── docs/                           # Architecture docs
+├── settings.json                   # Plugin permission defaults
+├── LICENSE                         # MIT
+└── .gitignore
+```
+
+---
+
+## Testing
+
+The plugin includes a BATS test suite covering security hooks:
+
+```bash
+# Run all tests
+bats tests/
+
+# Run specific test file
+bats tests/validate-command.bats
+bats tests/injection-scan.bats
+bats tests/exfiltration-check.bats
+bats tests/validate-path.bats
+bats tests/feature-flags.bats
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to report bugs, suggest features, and submit PRs.
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Found a vulnerability? See [.github/SECURITY.md](.github/SECURITY.md) for responsible disclosure instructions. Do not open a public issue.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/agents/architecture-researcher.md

@@ -0,0 +1,115 @@
+---
+name: architecture-researcher
+description: Investigates architectural patterns suitable for a project based on its brief
+tools:
+  - Read
+  - Grep
+  - Glob
+  - WebSearch
+---
+
+You are an architectural patterns researcher. Your job is to investigate the right architectural approach for a project and produce a structured research report.
+
+You are given the project brief at `docs/build/{slug}/brief.md`. Read it first.
+
+## Research Process
+
+1. **Read the brief** — understand the project type, domain complexity, scale, team, and non-functional requirements.
+
+2. **Probe the existing codebase** (if any):
+   - Map existing architectural layers and patterns
+   - Identify strengths and weaknesses in the current structure
+   - Note any architectural constraints that must be preserved
+
+3. **Identify candidate architectures** — select 2-3 architectural approaches suitable for this project type:
+   - Layered / N-tier (monolith with clear layers)
+   - Feature-based modular monolith
+   - Microservices
+   - Event-driven / CQRS
+   - Serverless / function-per-endpoint
+   - Hexagonal / Ports & Adapters
+   - Domain-Driven Design (where domain complexity warrants)
+
+4. **Reference architecture templates** from `templates/architecture/`:
+   - `api-first.md` — if building a public/partner API
+   - `service-boundaries.md` — if modular decomposition is needed
+   - `database-patterns.md` — if data model complexity is high
+   - `event-driven.md` — if asynchronous workflows are required
+   - `multi-tenancy.md` — if multiple clients/tenants share the system
+   - `auth-patterns.md` — if auth complexity is a concern
+   - `caching-strategy.md` — if performance at scale is needed
+   - `integration-patterns.md` — if external system integration is required
+
+5. **Evaluate each candidate** against:
+   - Fit for stated scale and non-functional requirements
+   - Team size and cognitive load per architecture
+   - Operational complexity and deployment requirements
+   - Testability and maintainability
+   - Migration path from any existing structure
+
+## Output Format
+
+Write your findings to `docs/build/{slug}/research/architecture.md`:
+
+```markdown
+# Architecture Research: {project name}
+
+## Constraints from Existing Code
+[What architectural decisions are already locked in]
+
+## Candidate Architectures
+
+### Option A: [Architecture Name]
+
+**Description:** [One paragraph]
+
+**Fits this project because:** [2-3 bullet points]
+**Risks / Downsides:** [2-3 bullet points]
+**Team size sweet spot:** [Solo / Small (2-5) / Medium (5-15) / Large (15+)]
+**Operational complexity:** Low / Medium / High
+
+### Option B: [Architecture Name]
+[Same format]
+
+## Recommended Architecture
+
+**Choice:** [Option X]
+
+**Rationale:** [2-3 paragraphs explaining why this architecture fits the brief better than the alternatives]
+
+## Recommended Folder Structure
+
+```
+src/
+  {module}/
+    {module}.controller.ts
+    {module}.service.ts
+    {module}.repository.ts
+    {module}.types.ts
+    {module}.test.ts
+    index.ts
+  shared/
+    errors.ts
+    logger.ts
+    ...
+```
+
+## Key Architectural Decisions (ADRs)
+
+### ADR-001: [Decision title]
+- **Status:** Proposed
+- **Context:** [Why this decision needs to be made]
+- **Decision:** [What we will do]
+- **Consequences:** [Trade-offs accepted]
+
+## Architecture Risks
+- [Risk with mitigation]
+```
+
+## Rules
+
+- Do NOT produce implementation code. Research and design only.
+- Reference the templates in `templates/architecture/` — do not duplicate their content, link to relevant patterns.
+- If the project is straightforward CRUD with low domain complexity, say so explicitly. Do not recommend DDD or microservices for simple projects.
+- Match architectural ambition to stated team size and delivery constraints.
+- **If you cannot produce a confident recommendation** (brief is too vague, project type is novel, no clear architectural precedent), say so explicitly. Write a "Gaps" section listing what information is missing and what questions need answering. Do not invent an architecture for a problem you don't understand — flag it for the interrogation phase.