@botdigit/agent-blueprint 1.0.0

package/templates/architecture/ARCHITECTURE_TEMPLATE.md

@@ -0,0 +1,81 @@
+# Architecture
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+**Last reviewed:** [YYYY-MM-DD]
+
+---
+
+## Architectural Style
+
+- **Style:** [modular monolith / microservices / serverless / client-server / event-driven / layered / hexagonal / or "not formalized"]
+- **Rationale:** [why this style, or "not documented"]
+
+---
+
+## Components
+
+### [Component Name]
+
+- **Responsibility:** [what it does]
+- **Communicates with:** [other components, external services]
+- **Technology:** [language, framework, or "inherits from project"]
+- **Deployment:** [how this component runs — same process, separate service, etc.]
+
+---
+
+## Data Flow
+
+[How data moves through the system — description or ASCII diagram]
+
+---
+
+## Boundaries
+
+- [boundary]: [what is inside, what is outside]
+- [boundary]: [what is inside, what is outside]
+
+---
+
+## Deployment Topology
+
+[How the system is deployed — processes, services, instances, shared resources]
+
+---
+
+## External Dependencies
+
+| Dependency | Purpose | Critical? | Failure mode |
+|---|---|---|---|
+| [service] | [what it does] | [yes / no] | [what happens if it fails] |
+
+---
+
+## Technology Choices
+
+| Area | Choice | Rationale |
+|---|---|---|
+| [area] | [choice] | [why] |
+| [area] | [choice] | [why] |
+
+---
+
+## Architecture Decisions
+
+[Link to `docs/architecture/decisions/` or list ADRs]
+
+---
+
+## Gaps and Risks
+
+| Gap | Severity | Recommendation |
+|---|---|---|
+| [gap] | [low / medium / high] | [recommendation] |
+
+---
+
+## Review History
+
+| Date | Reviewer | Notes |
+|---|---|---|
+| [date] | [reviewer] | [notes] |

package/templates/business-requirements/BUSINESS_REQUIREMENTS_TEMPLATE.md

@@ -0,0 +1,77 @@
+# Business Requirements
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+**Author:** [who wrote this]
+
+---
+
+## Business Model
+
+[How this project creates or captures value]
+
+---
+
+## Actors
+
+| Actor | Type | Can Do | Can See | Cannot Do |
+|---|---|---|---|---|
+| [name] | [type] | [actions] | [data] | [restricted] |
+
+---
+
+## Business Entities
+
+| Entity | Description | Key Data | Owner | Lifecycle |
+|---|---|---|---|---|
+| [name] | [what it represents] | [key fields] | [who owns it] | [lifecycle] |
+
+---
+
+## Business Processes
+
+### [Process Name]
+
+**Actor:** [who initiates]
+**Steps:**
+1. [step]
+2. [step]
+**End state:** [final state]
+**Failure handling:** [what happens on failure]
+
+---
+
+## Business Rules
+
+### [BR-XXX] — [Rule Name]
+
+**Category:** [authorization | validation | pricing | state | access | compliance | integrity]
+**Rule:** [description]
+**Condition:** [when it applies]
+**Outcome:** [what happens]
+**Exception:** [exceptions]
+**Invariant:** [what must never happen]
+
+---
+
+## State Machines
+
+### [Entity] Lifecycle
+
+**States:** [list]
+**Transitions:**
+- [state A] → [state B]: [trigger], [validation], [side effects]
+**Terminal states:** [list]
+
+---
+
+## Pricing (if applicable)
+
+[How pricing works. Where is the single source of truth?]
+
+---
+
+## Edge Cases
+
+- [scenario]: [how it is handled]
+- [scenario]: [how it is handled]

package/templates/changelog/CHANGELOG_TEMPLATE.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Version] — [Date]
+
+### Added
+
+- [what was added]
+
+### Changed
+
+- [what was changed]
+
+### Deprecated
+
+- [what is deprecated]
+
+### Removed
+
+- [what was removed]
+
+### Fixed
+
+- [what was fixed]
+
+### Security
+
+- [security-relevant changes]
+
+---
+
+## [Version] — [Date]
+
+[Repeat structure]

package/templates/database/DATABASE_TEMPLATE.md

@@ -0,0 +1,77 @@
+# Database
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+
+---
+
+## Database Engine
+
+- **Primary:** [PostgreSQL / MySQL / SQLite / MongoDB / etc.]
+- **Version:** [if known]
+- **Connection:** [how the application connects — env vars, config, connection pool]
+
+---
+
+## Schema Overview
+
+[Link to migrations or schema dump, or describe the schema structure]
+
+---
+
+## Migrations
+
+- **System:** [ migrations / flyway / alembic / prisma / artisan / rails / or "none" ]
+- **Location:** [path]
+- **Process:** [how migrations are run — manually, CI, on deploy]
+
+---
+
+## ORM / Query Builder
+
+- **Tool:** [Eloquent / ActiveRecord / Prisma / SQLAlchemy / SQLx / raw SQL / or "none"]
+- **Pattern:** [how the project uses it]
+
+---
+
+## Data Model
+
+### [Table / Collection Name]
+
+**Purpose:** [what this table represents]
+**Columns / Fields:**
+- [name]: [type], [constraints], [description]
+**Relationships:**
+- [relation]: [type], [description]
+**Indexes:** [if notable]
+**Notes:** [any special considerations]
+
+---
+
+## Data Integrity
+
+- [constraint or rule]: [description]
+- [constraint or rule]: [description]
+
+---
+
+## Sensitive Data
+
+- [data type]: [how it is protected — encryption, access control, retention]
+- [data type]: [how it is protected]
+
+---
+
+## Backups
+
+- **Strategy:** [description or "not defined"]
+- **Frequency:** [if known]
+- **Retention:** [if known]
+- **Restore tested:** [yes / no / unknown]
+
+---
+
+## Data Retention and Deletion
+
+- [policy or "not defined"]
+- [policy or "not defined"]

package/templates/deployment/DEPLOYMENT_TEMPLATE.md

@@ -0,0 +1,80 @@
+# Deployment
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+
+---
+
+## Deployment Model
+
+- **Type:** [manual / CI/CD / platform-managed / or "mixed"]
+- **Platform:** [Vercel / AWS / GCP / Azure / VPS / Docker / Kubernetes / or "unknown"]
+- **Environments:** [production, staging, development — describe each]
+
+---
+
+## Build Process
+
+[How the project is built — commands, steps, artifacts]
+
+---
+
+## Deployment Process
+
+[How the project is deployed — steps, triggers, approvals]
+
+---
+
+## Rollback
+
+- **Strategy:** [how to roll back — redeploy previous version, database rollback, or "not defined"]
+- **Tested:** [yes / no / unknown]
+
+---
+
+## Environment Configuration
+
+- **Configuration method:** [.env / config files / secrets manager / or "mixed"]
+- **Secrets management:** [how secrets are managed]
+- **Environment-specific settings:** [what differs between environments]
+
+---
+
+## CI/CD
+
+- **System:** [GitHub Actions / GitLab CI / CircleCI / Jenkins / or "none"]
+- **Pipeline stages:** [list stages — build, test, deploy, or "not configured"]
+- **Triggers:** [what triggers a deployment]
+
+---
+
+## Health Checks and Monitoring
+
+- **Health checks:** [Liveness / readiness / or "not configured"]
+- **Monitoring:** [what is monitored — uptime, errors, performance, or "not configured"]
+- **Alerting:** [who gets alerted and when]
+
+---
+
+## Scaling
+
+- **Current scale:** [how the project runs today]
+- **Scaling strategy:** [manual / auto-scaling / or "not defined"]
+- **Bottlenecks:** [known scaling limits]
+
+---
+
+## Disaster Recovery
+
+- **Strategy:** [description or "not defined"]
+- **Backup:** [what is backed up and how often]
+- **Restore tested:** [yes / no / unknown]
+- **RTO / RPO:** [if defined]
+
+---
+
+## Review History
+
+| Date | Reviewer | Notes |
+|---|---|---|
+| [date] | [reviewer] | [notes] |

package/templates/project-brief/PROJECT_BRIEF_TEMPLATE.md

@@ -0,0 +1,72 @@
+# Project Brief
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+**Author:** [who wrote this]
+**Status:** [draft | in review | approved]
+
+---
+
+## Overview
+
+What is this project?
+
+[2-3 sentences. What does it do? Who is it for? Why does it exist?]
+
+---
+
+## Goals
+
+- [goal]
+- [goal]
+- [goal]
+
+---
+
+## Non-Goals
+
+- [what is explicitly out of scope]
+- [what is explicitly out of scope]
+
+---
+
+## Target Users
+
+- [user type]: [description]
+
+---
+
+## Core Capabilities
+
+- [capability]: [brief description]
+- [capability]: [brief description]
+
+---
+
+## Constraints
+
+- [constraint]: [description]
+- [constraint]: [description]
+
+---
+
+## Technology (known or chosen)
+
+- [language / framework / database / infrastructure]
+- [or "not yet decided"]
+
+---
+
+## Success Criteria
+
+How will we know this project is successful?
+
+- [measurable criterion]
+- [measurable criterion]
+
+---
+
+## Open Questions
+
+- [question]
+- [question]

package/templates/runbook/RUNBOOK_TEMPLATE.md

@@ -0,0 +1,54 @@
+# Runbook: [Title]
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+**Owner:** [who owns this]
+
+---
+
+## Purpose
+
+[What this runbook covers and when to use it]
+
+---
+
+## Prerequisites
+
+- [access needed]
+- [tools needed]
+- [permissions needed]
+
+---
+
+## Procedures
+
+### [Scenario / Task]
+
+**When:** [when this procedure applies]
+**Steps:**
+1. [step]
+2. [step]
+**Expected outcome:** [what should happen]
+**If it fails:** [what to do]
+
+---
+
+### [Scenario / Task]
+
+[Same structure]
+
+---
+
+## Common Issues
+
+| Symptom | Cause | Resolution |
+|---|---|---|
+| [symptom] | [cause] | [resolution] |
+| [symptom] | [cause] | [resolution] |
+
+---
+
+## Contacts
+
+- [role]: [contact]
+- [role]: [contact]

package/templates/security/SECURITY_TEMPLATE.md

@@ -0,0 +1,93 @@
+# Security
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+**Last reviewed:** [YYYY-MM-DD]
+
+---
+
+## Attack Surface
+
+[What is exposed to the internet, to users, to third parties]
+
+---
+
+## Authentication
+
+- **Mechanism:** [how users authenticate]
+- **Session management:** [how sessions are managed]
+- **Password storage:** [how passwords are stored — should be hashed]
+- **MFA:** [available or not]
+- **Admin authentication:** [how admin access is protected]
+
+---
+
+## Authorization
+
+- **Model:** [RBAC / ABAC / custom / or "not formalized"]
+- **Enforcement:** [where authorization is checked — on every endpoint, some endpoints, or unclear]
+- **Access control review:** [when access control was last reviewed]
+
+---
+
+## Data Protection
+
+- **In transit:** [TLS / HTTPS / or "not confirmed"]
+- **At rest:** [encryption / or "not confirmed"]
+- **Secrets management:** [env vars / secrets manager / or "issue — hardcoded"]
+- **PII handling:** [how PII is handled and protected]
+- **Data minimization:** [are we collecting only what we need?]
+
+---
+
+## Input Validation
+
+- **Client-side:** [what client-side validation exists]
+- **Server-side:** [what server-side validation exists — must exist for all sensitive inputs]
+- **SQL injection protection:** [parameterized queries / ORM / or "needs review"]
+- **Output encoding:** [context-appropriate encoding]
+
+---
+
+## Dependencies
+
+- **Review cadence:** [how often dependencies are reviewed]
+- **Known vulnerabilities:** [any known issues, or "none known"]
+- **Lockfile:** [committed or not]
+
+---
+
+## Logging and Monitoring
+
+- **Security events logged:** [what is logged]
+- **Sensitive data in logs:** [are logs free of passwords, tokens, PII?]
+- **Alerting:** [is there alerting for suspicious activity?]
+
+---
+
+## Infrastructure Security
+
+- **Container security:** [run as non-root / or "unknown"]
+- **Network:** [security groups / firewalls / or "not reviewed"]
+- **TLS configuration:** [if known]
+- **Exposed services:** [list of internet-exposed services]
+
+---
+
+## Business Logic Security
+
+[Known business logic security concerns — pricing manipulation, workflow bypass, race conditions, etc.]
+
+---
+
+## Findings
+
+[Security findings from reviews and audits]
+
+---
+
+## Review History
+
+| Date | Reviewer | Notes |
+|---|---|---|
+| [date] | [reviewer] | [notes] |

package/templates/testing/TESTING_TEMPLATE.md

@@ -0,0 +1,87 @@
+# Testing
+
+**Project:** [name]
+**Date:** [YYYY-MM-DD]
+
+---
+
+## Current State
+
+- **Tests exist:** [yes / no / partially]
+- **Test framework:** [pytest / PHPUnit / Jest / RSpec / or "none"]
+- **Test types in use:** [unit / integration / E2E / contract / or "none"]
+- **CI integration:** [yes / no / partial]
+- **Test reliability:** [stable / flaky / unknown]
+- **Test execution time:** [if known]
+
+---
+
+## What Is Tested
+
+- [feature / flow / logic]: [test type]
+- [feature / flow / logic]: [test type]
+
+---
+
+## What Is Not Tested (Gaps)
+
+- [gap]: [priority]
+- [gap]: [priority]
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+- **Scope:** [what unit tests cover]
+- **Framework:** [if applicable]
+- **Convention:** [how tests are written]
+
+### Integration Tests
+
+- **Scope:** [what integration tests cover]
+- **Framework:** [if applicable]
+- **Data handling:** [how test data and database are managed]
+
+### End-to-End Tests
+
+- **Scope:** [what E2E tests cover — critical user flows]
+- **Framework:** [if applicable]
+
+### Contract Tests
+
+- **Scope:** [what contract tests cover — if applicable]
+- **Framework:** [if applicable]
+
+---
+
+## Test Quality Standards
+
+- Tests are deterministic.
+- Tests assert meaningful behavior.
+- Tests fail for the right reason.
+- Tests are readable.
+- Tests are maintained.
+
+---
+
+## CI
+
+- **When tests run:** [on push, on PR, on merge, or "not configured"]
+- **What happens on failure:** [blocked merge, notification, or "not configured"]
+- **Coverage reporting:** [yes / no / unknown]
+
+---
+
+## Recommendations
+
+[Any recommended improvements to the testing setup]
+
+---
+
+## Review History
+
+| Date | Reviewer | Notes |
+|---|---|---|
+| [date] | [reviewer] | [notes] |