@botdigit/agent-blueprint 1.0.0

package/stacks/go/SKILL.md

@@ -0,0 +1,61 @@
+# Go Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with Go projects. Activated automatically when `go.mod` and `.go` files are detected.
+
+---
+
+## Conventions
+
+### Idiomatic Go
+
+- Follow Effective Go and the Go FAQs.
+- Simple, readable code is preferred over clever code.
+- Explicit error handling is a feature. Do not ignore errors with `_` unless there is a specific reason and a comment.
+- Zero values should be useful where practical.
+
+### Error handling
+
+- Errors are values. Handle them.
+- Wrap errors with context using `fmt.Errorf("...: %w", err)` or similar.
+- Do not use panics for expected errors.
+
+### Types
+
+- Go's type system is structural. Use it.
+- Interfaces should be small and defined where they are used, not where they are implemented.
+- Avoid unnecessary abstraction. Go prefers concrete code over abstraction layers.
+
+### Concurrency
+
+- Goroutines are cheap but not free. Do not spawn unbounded goroutines.
+- Use channels, `sync`, or context appropriately. Each has a purpose.
+- Always have a plan for canceling concurrent work (context, done channel).
+
+### Dependencies
+
+- `go mod` manages dependencies. `go.sum` should be committed.
+- Vendor directory is optional and project-dependent.
+
+### Tooling
+
+- `gofmt` / `goimports` for formatting. The project should enforce this.
+- `go vet` for static analysis.
+- The project may use additional linters. Follow the project's choice.
+
+---
+
+## Anti-patterns
+
+- Ignoring errors.
+- Using goroutines without a way to stop them.
+- Over-engineering with interfaces and abstraction layers.
+- Unbounded concurrency.

package/stacks/java/SKILL.md

@@ -0,0 +1,58 @@
+# Java Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with Java projects. Activated automatically when `pom.xml`, `build.gradle`, or `.java` files are detected.
+
+---
+
+## Conventions
+
+### Version
+
+- Java 17 or 21 are current LTS versions. The project's version is in the build file or runtime.
+- Older versions should be noted as technical debt if upgrade is feasible.
+
+### Style
+
+- Follow the project's style guide. If none exists, follow standard Java conventions.
+- Use the project's formatter and linter (`checkstyle`, `spotless`, ` ErrorProne`, ` SonarQube`, or similar).
+
+### Type system
+
+- Java has a static type system. Use it.
+- Avoid `Object` and raw types where specific types are known.
+- Generics are a tool, not a requirement for every class.
+
+### Error handling
+
+- Use exceptions for exceptional conditions.
+- Checked exceptions are a Java feature. Use them where appropriate, but do not overuse them to the point of unreadability.
+- Do not swallow exceptions silently.
+
+### Dependencies
+
+- Maven: `pom.xml` manages dependencies.
+- Gradle: `build.gradle` manages dependencies.
+- Review dependencies for maintenance and licensing.
+
+### Frameworks
+
+- Spring Boot is common. If the project uses it, follow the framework skill.
+- The framework skill is more specific than this stack skill. Both may be active.
+
+---
+
+## Anti-patterns
+
+- Empty catch blocks.
+- Overuse of inheritance when composition would do.
+- Unnecessary abstraction layers.
+- Mixing concerns in large classes.

package/stacks/javascript/SKILL.md

@@ -0,0 +1,47 @@
+# JavaScript Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with JavaScript projects. Activated automatically when `package.json` and `.js` files are detected.
+
+---
+
+## Conventions
+
+### Types
+
+- JavaScript has no type system. Data at boundaries (API inputs, external data, user input) must be validated at runtime.
+- Document expected shapes in JSDoc where practical.
+- If the project grows, consider whether TypeScript would reduce risk. Propose the change in an ADR if it is warranted — do not impose it.
+
+### Module system
+
+- Use ES modules (`import`/`export`) if the project targets modern environments.
+- Follow the project's existing module convention.
+
+### Error handling
+
+- Use `Error` instances, not string throws.
+- Handle errors at the appropriate level.
+- Do not silently swallow errors.
+
+### Tooling
+
+- The project's linting and formatting configuration is the source of truth.
+- `package-lock.json` or `npm-shrinkwrap.json` should be committed if the project uses npm.
+
+---
+
+## Anti-patterns
+
+- Assuming data shapes without validation.
+- Callback pyramids where async/await is available.
+- Unhandled promise rejections.
+- Global state without clear ownership.

package/stacks/php/SKILL.md

@@ -0,0 +1,51 @@
+# PHP Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with PHP projects. Activated automatically when `composer.json` or `.php` files are detected.
+
+---
+
+## Conventions
+
+### Version
+
+- PHP 8.x is the current standard. The project's required version is in `composer.json` or `php.ini`/runtime.
+- Older PHP versions should be noted as technical debt if the project would benefit from upgrading.
+
+### Type system
+
+- PHP has a type system. Use it: parameter types, return types, property types, iterable and array types where appropriate.
+- `strict_types=1` is recommended for new code. Respect the project's existing declaration.
+- Do not use `mixed` as a substitute for thinking about the type.
+
+### Dependencies
+
+- `composer.lock` should be committed for applications.
+- Review dependencies. PHP has a large ecosystem; not all packages are equally maintained.
+
+### Error handling
+
+- Use exceptions for exceptional conditions.
+- Configure error reporting appropriately for development and production.
+- Do not expose PHP errors to users in production.
+
+### Tooling
+
+- The project's linter (`phpstan`, `psalm`, `pint`, `php-cs-fixer`, or similar) is the project's choice.
+
+---
+
+## Anti-patterns
+
+- Ignoring return types and parameter types.
+- Using arrays where a typed object would be clearer.
+- Mixing presentation and logic without a reason.
+- Hardcoded secrets in PHP files.

package/stacks/python/SKILL.md

@@ -0,0 +1,52 @@
+# Python Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with Python projects. Activated automatically when `pyproject.toml`, `requirements.txt`, `setup.py`, or `.py` files are detected.
+
+---
+
+## Conventions
+
+### Version and tooling
+
+- The project's Python version is determined by `pyproject.toml`, `requirements.txt`, or the runtime environment. Follow it.
+- Use virtual environments. The project's choice of `venv`, `poetry`, `uv`, `pipenv`, or similar is the project's choice.
+
+### Type hints
+
+- Use type hints where they add clarity. They are optional in Python but valuable in larger projects.
+- Runtime validation is still required for external data. Type hints are not runtime checks.
+- `mypy` or similar may be in use. Follow the project's strictness setting.
+
+### Code style
+
+- Follow PEP 8 unless the project has chosen otherwise.
+- The project's formatter (`ruff`, `black`, `autopep8`, or none) is the project's choice.
+
+### Error handling
+
+- Use specific exception types.
+- Do not use bare `except:`.
+- Handle exceptions at the appropriate level.
+
+### Dependencies
+
+- Pin versions in production. `requirements.txt` with pinned versions, `poetry.lock`, or similar.
+- Review dependencies for known vulnerabilities.
+
+---
+
+## Anti-patterns
+
+- Bare `except:`.
+- Using exceptions for control flow where a conditional would do.
+- Global mutable state.
+- Assuming types at runtime based on type hints.

package/stacks/ruby/SKILL.md

@@ -0,0 +1,51 @@
+# Ruby Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with Ruby projects. Activated automatically when `Gemfile` or `.rb` files are detected.
+
+---
+
+## Conventions
+
+### Version
+
+- Ruby 3.x is current. The project's version is in the `Gemfile` or `.ruby-version`.
+- Follow the project's version.
+
+### Style
+
+- Follow the community style guide unless the project has chosen otherwise.
+- The project's linter and formatter (`rubocop`, or none) is the project's choice.
+
+### Types
+
+- Ruby is dynamically typed. Runtime validation is required for external data.
+- Type hints (RBS, Sorbet) may be in use. Follow the project's choice.
+
+### Error handling
+
+- Use exceptions for exceptions.
+- Handle exceptions at the appropriate level.
+- Do not use exceptions for control flow.
+
+### Dependencies
+
+- `Gemfile.lock` should be committed.
+- Review gems for maintenance and licensing.
+
+---
+
+## Anti-patterns
+
+- Magic numbers and strings without explanation.
+- Overly clever metaprogramming without clear necessity.
+- N+1 queries (Ruby projects often use ORMs; this is a common issue).
+- Silent failures (swallowed exceptions, `nil` where an error would be clearer).

package/stacks/rust/SKILL.md

@@ -0,0 +1,55 @@
+# Rust Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with Rust projects. Activated automatically when `Cargo.toml` is detected.
+
+---
+
+## Conventions
+
+### Memory and safety
+
+- Rust's ownership system is a feature. Do not use `unsafe` unless you have a specific, documented reason.
+- Prefer safe abstractions over unsafe code.
+- When `unsafe` is necessary, document why and scope it as tightly as possible.
+
+### Error handling
+
+- Use `Result` for fallible operations. Do not use `panic` for recoverable errors.
+- Use `thiserror` or similar for library error types, `anyhow` or similar for applications — matching the project's choice.
+- Errors should be informative. A `Result<(), Box<dyn Error>>` is acceptable for a quick script; a typed error enum is better for a library or critical path.
+
+### Types
+
+- Make illegal states unrepresentable where practical.
+- Use the type system to encode constraints.
+- Avoid `unwrap()` in production code. Use `expect()` with a message when panicking is the intended behavior, and handle the error properly when it is not.
+
+### Async
+
+- The project's async runtime is its choice (`tokio`, `async-std`, or none for synchronous projects).
+- Do not mix runtimes.
+- Async does not make a slow operation fast. It allows concurrent waiting. Understand the difference.
+
+### Dependencies
+
+- `Cargo.lock` should be committed for applications.
+- Review dependencies for licensing and maintenance status.
+- Rust compiles what it needs. Unused dependencies are not a runtime cost but are a maintenance burden.
+
+---
+
+## Anti-patterns
+
+- Using `unwrap()` as a substitute for error handling.
+- Using `unsafe` to avoid learning the safe API.
+- Over-using generics to the point of unreadability.
+- Ignoring `clippy` warnings without reason.

package/stacks/typescript/SKILL.md

@@ -0,0 +1,55 @@
+# TypeScript Stack Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (activated by orchestrator on detection)
+**Outputs:** (none — guidance only)
+
+---
+
+## Purpose
+
+Guidance for working with TypeScript projects. Activated automatically when `package.json` and `.ts` files are detected.
+
+---
+
+## Conventions
+
+### Types
+
+- Prefer `type` for unions and intersections, `interface` for object shapes that may be extended.
+- Do not use `any`. Use `unknown` when the type is genuinely unknown, and narrow from there.
+- Export types that are part of the public API.
+- Avoid type assertions (`as T`) unless you have a specific reason and a comment explaining it.
+
+### Runtime
+
+- TypeScript compiles to JavaScript. Types are not runtime checks. Validate data at boundaries (API inputs, external data, user input) using runtime validation, not type assertions.
+- Use a runtime validation library if the project handles external data (Zod, Valibot, io-ts, or similar). The choice is the project's.
+
+### Module system
+
+- Use ES modules (`import`/`export`).
+- Prefer explicit imports over namespace imports.
+- Barrel files (`index.ts`) are acceptable for public API surfaces but should not be overused.
+
+### Error handling
+
+- Use typed errors where appropriate.
+- Do not throw string literals.
+- Handle errors at the appropriate level — not everywhere, not nowhere.
+
+### Tooling
+
+- The project's tsconfig is the source of truth. Do not override it without reason.
+- Strict mode should be on unless there is a documented reason.
+- The project's linter and formatter are the project's choice. Follow them.
+
+---
+
+## Anti-patterns
+
+- Using `any` to silence the compiler.
+- Type assertions to bypass type errors without understanding why the error exists.
+- Duplicate types between frontend and backend without a shared source.
+- Runtime assumptions based on TypeScript types.

package/templates/adr/ADR-TEMPLATE.md

@@ -0,0 +1,64 @@
+# ADR: [Title]
+
+**Status:** [proposed | accepted | deprecated | superseded]
+**Date:** [YYYY-MM-DD]
+**Deciders:** [who decided]
+**Superseded by:** [ADR number, if applicable]
+**Supersedes:** [ADR number, if applicable]
+
+---
+
+## Context
+
+What is the problem or decision this ADR addresses? Why is this decision needed?
+
+Describe the situation. Include relevant constraints, requirements, and forces.
+
+---
+
+## Decision
+
+What was decided?
+
+Be specific. This is what the project will do (or did).
+
+---
+
+## Consequences
+
+What does this decision imply?
+
+### Positive
+
+- [consequence]
+- [consequence]
+
+### Negative
+
+- [consequence]
+- [consequence]
+
+### Neutral
+
+- [consequence]
+- [consequence]
+
+---
+
+## Alternatives Considered
+
+What else was considered and why was it not chosen?
+
+### [Alternative 1]
+
+[Brief description and reason for rejection]
+
+### [Alternative 2]
+
+[Brief description and reason for rejection]
+
+---
+
+## References
+
+[Any relevant documents, issues, discussions, or external references]

package/templates/api-spec/API_SPEC_TEMPLATE.md

@@ -0,0 +1,137 @@
+# API Specification Template
+
+**API Name:** [e.g., Core REST API / Public V1 API]
+**Base URL:** `https://api.example.com/v1`
+**Authentication:** [Bearer Token (JWT) / API Key / Session Cookie]
+**Protocol:** [REST / GraphQL / gRPC]
+**Last Updated:** [YYYY-MM-DD]
+**Status:** [Draft / Stable / Deprecated]
+
+---
+
+## 1. Authentication & Security
+
+- **Scheme:** `Authorization: Bearer <token>`
+- **Token Expiry:** [e.g., Access 15m, Refresh 7d]
+- **Rate Limits:**
+  - Standard tier: `100 req / minute`
+  - Authenticated tier: `1000 req / minute`
+  - Rate limit response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
+
+---
+
+## 2. Standard Response Envelopes
+
+### Success Envelope (200 OK / 201 Created)
+```json
+{
+  "success": true,
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 150
+  }
+}
+```
+
+### Error Envelope (4xx / 5xx)
+```json
+{
+  "success": false,
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "Human-readable error explanation",
+    "details": []
+  },
+  "request_id": "req_01hz8..."
+}
+```
+
+---
+
+## 3. Endpoints
+
+### 3.1 [Resource Name] Collection
+
+#### `GET /v1/[resources]`
+*List resources with pagination and filters.*
+
+**Query Parameters:**
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `page` | integer | No | `1` | Current page number |
+| `limit` | integer | No | `20` | Items per page (max: 100) |
+| `sort` | string | No | `created_at:desc` | Sort field and direction |
+| `filter` | string | No | - | Query filter |
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "res_12345",
+      "created_at": "2026-09-09T12:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 1
+  }
+}
+```
+
+---
+
+#### `POST /v1/[resources]`
+*Create a new resource.*
+
+**Request Body:**
+```json
+{
+  "name": "string (required, max: 120)",
+  "status": "ACTIVE | INACTIVE"
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "res_12345",
+    "status": "ACTIVE"
+  }
+}
+```
+
+---
+
+### 3.2 Individual Resource Operations
+
+#### `GET /v1/[resources]/:id`
+*Fetch single resource by ID.*
+
+#### `PUT /v1/[resources]/:id`
+*Replace or full update.*
+
+#### `PATCH /v1/[resources]/:id`
+*Partial update of fields.*
+
+#### `DELETE /v1/[resources]/:id`
+*Delete or soft-delete resource.*
+
+---
+
+## 4. Error Code Reference
+
+| HTTP Status | Error Code | Description |
+|---|---|---|
+| `400 Bad Request` | `VALIDATION_FAILED` | Request payload failed schema validation |
+| `401 Unauthorized` | `UNAUTHENTICATED` | Missing or invalid auth credentials |
+| `403 Forbidden` | `PERMISSION_DENIED` | Insufficient role or scope |
+| `404 Not Found` | `NOT_FOUND` | Target entity does not exist |
+| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Request quota exhausted |
+| `500 Internal Server Error` | `INTERNAL_ERROR` | Unexpected server fault |