@botdigit/agent-blueprint 1.0.0

package/skills/06-codebase-audit/SKILL.md

@@ -0,0 +1,127 @@
+# 06-Codebase-Audit Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context
+**Outputs:** codebase-audit.md, code-gaps.md
+
+---
+
+## Purpose
+
+Inspect the existing codebase to understand what is there, how it is structured, what conventions it follows, and what problems exist — before making any changes.
+
+Inspect before assuming.
+
+---
+
+## Process
+
+### 1. Map the code structure
+
+- Directory layout
+- Entry points
+- Module/package boundaries
+- Public vs private interfaces
+- Shared code
+- Standalone scripts
+
+### 2. Identify conventions
+
+- Naming conventions (files, functions, variables, classes)
+- Code style (formatting, linting, imports)
+- Architectural patterns in use (MVC, layered, domain-driven, etc.)
+- Error handling patterns
+- Logging patterns
+- Testing patterns (if tests exist)
+- Configuration patterns
+
+### 3. Identify entry points and flows
+
+For each major feature or flow:
+- Where it enters the system
+- What components it touches
+- What data it reads and writes
+- What external services it calls
+- What errors can occur
+
+### 4. Assess code quality
+
+Look for:
+- Duplicated code
+- Large functions or files
+- Mixed responsibilities
+- Copy-paste architecture
+- Dead code
+- commented-out code
+- TODOs and FIXMEs (and whether they are tracked)
+- Magic values
+- Inconsistent error handling
+- Missing input validation
+- Missing type safety where the language supports it
+
+### 5. Assess test situation
+
+- Do tests exist?
+- What is tested?
+- What is not tested?
+- Test quality (unit, integration, end-to-end)
+- Test coverage of critical paths
+- Whether tests are run in CI
+
+### 6. Identify technical debt
+
+Record debt in these categories:
+- Code-level debt (duplication, complexity, poor naming)
+- Architecture-level debt (wrong boundaries, coupling, missing abstractions)
+- Test debt (missing tests, brittle tests, no CI)
+- Documentation debt (missing, outdated)
+- Dependency debt (outdated, unmaintained, too many)
+- Security debt (see 07-security for detailed security audit)
+
+---
+
+## Output
+
+### codebase-audit.md
+
+```
+Codebase Audit
+==============
+Project: [name]
+Audit date: [date]
+Auditor: [agent or person]
+
+Structure:
+  [description of code layout]
+
+Conventions:
+  [naming, style, patterns detected]
+
+Entry points:
+  [list]
+
+Code quality:
+  Strengths: [what is good]
+  Problems: [what is not good]
+  Estimated complexity: [low | medium | high]
+
+Test situation:
+  Tests exist: [yes | no]
+  Coverage: [description or "unknown"]
+  CI: [yes | no | unknown]
+
+Technical debt:
+  [list by category]
+```
+
+### code-gaps.md
+
+```
+Code Gaps
+=========
+[Gap ID]: [description]
+Severity: [low | medium | high]
+Category: [code | architecture | test | docs | dependency]
+Recommendation: [what to do]
+```

package/skills/07-security/SKILL.md

@@ -0,0 +1,159 @@
+# 07-Security Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context, business-architecture
+**Outputs:** security.md, security-findings.md
+
+---
+
+## Purpose
+
+Review the project's security posture. Security and data integrity come before features.
+
+This skill is mandatory for projects that handle user data, payments, authentication, PII, or external integrations. It is optional for static sites and tools that do not handle sensitive data.
+
+---
+
+## Process
+
+### 1. Identify the attack surface
+
+- What endpoints or interfaces accept input?
+- What data is collected, stored, or transmitted?
+- What authentication and authorization exist?
+- What third-party services are integrated?
+- What data crosses trust boundaries?
+- What is exposed to the internet?
+- What is internal-only?
+
+### 2. Review authentication
+
+- How do users authenticate?
+- Are credentials stored securely?
+- Are sessions managed correctly?
+- Is MFA available where it should be?
+- Are password policies reasonable?
+- Are there default or backdoor accounts?
+- Is there an admin authentication path? Is it appropriately protected?
+
+### 3. Review authorization
+
+- Can users access data they do not own?
+- Can users perform actions they should not?
+- Are authorization checks on every endpoint, or only some?
+- Is there privilege escalation risk?
+- Are roles and permissions clearly defined?
+- Can permissions be bypassed by changing parameters, IDs, or paths?
+
+### 4. Review input handling
+
+- Is all input validated?
+- Is validation on the client sufficient? (it is not)
+- Are SQL queries parameterized?
+- Are queries using an ORM correctly (no raw SQL where avoidable)?
+- Is output encoded for its context (HTML, JSON, SQL, shell)?
+- Are file uploads handled safely?
+- Are file types validated server-side?
+- Are file sizes limited?
+
+### 5. Review data protection
+
+- Is sensitive data encrypted at rest?
+- Is data encrypted in transit?
+- Are secrets in code, config files, or env vars? (all are problems; env vars are the least bad)
+- Are API keys and tokens exposed in client-side code?
+- Is PII handled according to the project's obligations?
+- Is data retention defined and implemented?
+- Can data be deleted when required?
+
+### 6. Review dependencies
+
+- Are dependencies up to date?
+- Are there known vulnerabilities in dependencies?
+- Are unused dependencies removed?
+- Are dependencies from trusted sources?
+- Are lockfiles committed?
+
+### 7. Review logging and monitoring
+
+- Are security events logged?
+- Are logs free of sensitive data?
+- Is there alerting for suspicious activity?
+- Can you detect a breach?
+
+### 8. Review business logic security
+
+Business logic vulnerabilities are not caught by generic scanners. Examine:
+- Can pricing be manipulated?
+- Can workflows be bypassed?
+- Can state transitions be forced out of order?
+- Can users affect data they should not?
+- Are there race conditions in critical operations?
+- Can features be accessed before they should be?
+- Can free users access paid features?
+- Can admin features be accessed by non-admins?
+
+### 9. Review infrastructure security
+
+If infrastructure is detectable:
+- Are containers run as root?
+- Are secrets in environment variables or mounted files?
+- Are security groups / firewalls appropriate?
+- Is TLS configured?
+- Are backups encrypted?
+- Are there unnecessary exposed ports or services?
+
+---
+
+## Severity Levels
+
+| Severity | Meaning | Response |
+|---|---|---|
+| Critical | Active exploit possible; data breach or system compromise likely | Fix immediately; block release if unfixed |
+| High | Significant risk; exploitation likely with some effort | Fix before next release; prioritize |
+| Medium | Notable risk; exploitation possible but constrained | Fix in current or next sprint |
+| Low | Minor issue; hard to exploit or low impact | Track and fix when convenient |
+| Informational | Worth noting; not a vulnerability | Document |
+
+---
+
+## Output
+
+### security.md
+
+```
+Security
+========
+Attack surface: [description]
+Authentication: [mechanism, assessment]
+Authorization: [mechanism, assessment]
+Data protection: [assessment]
+Dependencies: [assessment]
+Logging: [assessment]
+Infrastructure: [assessment if detectable]
+Business logic security: [assessment]
+```
+
+### security-findings.md
+
+```
+Security Findings
+=================
+[Finding ID]: [description]
+Severity: [critical | high | medium | low | informational]
+Location: [where found]
+Impact: [what can happen]
+Recommendation: [what to do]
+```
+
+---
+
+## Critical Rules
+
+- Never hardcode secrets. Ever.
+- Never trust client-side validation alone.
+- Never skip authorization checks on any endpoint that touches sensitive data.
+- Never store passwords in plaintext.
+- Never expose internal errors to users.
+- Never ignore known vulnerabilities in dependencies.

package/skills/08-testing/SKILL.md

@@ -0,0 +1,120 @@
+# 08-Testing Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context, codebase-audit
+**Outputs:** testing.md, test-gaps.md
+
+---
+
+## Purpose
+
+Establish a testing strategy and verify that changes are tested. Every major change needs tests.
+
+---
+
+## Process
+
+### 1. Assess current testing
+
+- Do tests exist?
+- What kinds? (unit, integration, end-to-end, contract, performance, security)
+- What is tested and what is not?
+- Is there a testing culture (tests written with features)?
+- Are tests run in CI?
+- How long do tests take?
+- Are tests reliable (flaky or stable)?
+
+### 2. Identify what must be tested
+
+Testing priority:
+
+1. **Business rules** — the rules that make the business work. If these are wrong, the product is wrong.
+2. **Data integrity** — operations that create, modify, or delete data. Wrong data is worse than no data.
+3. **Security boundaries** — authentication, authorization, access control.
+4. **Integration points** — external services, APIs, databases.
+5. **Critical user flows** — the paths users take to accomplish core tasks.
+6. **Edge cases** — failure modes, boundary conditions, invalid input.
+
+### 3. Define the testing strategy
+
+For each type of test, decide:
+- What it covers
+- When it runs
+- How it is written
+- How it is maintained
+
+Testing pyramid (general guidance, adapt to project):
+
+- **Unit tests** — fast, isolated, many. Test business logic, pure functions, transformations.
+- **Integration tests** — moderate speed, test component interactions, database, external services with test doubles where appropriate.
+- **End-to-end tests** — slow, test complete user flows. Few, focused on critical paths.
+- **Contract tests** — if APIs are consumed by other systems.
+- **Performance tests** — if performance is a requirement. See 09-performance.
+
+### 4. Define test quality standards
+
+- Tests must be deterministic. A test that fails intermittently erodes trust.
+- Tests must assert something meaningful. Assertions that cannot fail are noise.
+- Tests should fail for the right reason. A test that passes when it should fail is dangerous.
+- Tests should be readable. A test is documentation of expected behavior.
+- Tests should be maintainable. Brittle tests that break on every change will be deleted.
+
+### 5. Identify test gaps
+
+Record gaps by priority. Not everything can be tested immediately. Prioritize by risk:
+- Untested business-critical logic → highest priority
+- Untested security boundaries → high priority
+- Untested integrations → high priority
+- Untested edge cases → medium priority
+- Missing unit tests for non-critical code → lower priority
+
+---
+
+## What to Test
+
+| What | Test Type | Priority |
+|---|---|---|
+| Business rules | Unit | Highest |
+| Data integrity (create/update/delete) | Integration | Highest |
+| Authentication | Integration / E2E | Highest |
+| Authorization | Integration / E2E | Highest |
+| Payment / billing logic | Unit + Integration | Highest |
+| API endpoints | Integration / Contract | High |
+| User workflows | E2E | High |
+| Database migrations | Integration | High |
+| File upload / processing | Integration | Medium |
+| Email / notifications | Integration (with test double) | Medium |
+| Third-party integration Contracts | Contract | Medium |
+| Reporting / aggregation | Unit + Integration | Medium |
+| UI rendering (non-interactive) | Unit / Component | Lower |
+| Visual styling | Manual / visual regression | Lower |
+
+---
+
+## Output
+
+### testing.md
+
+```
+Testing
+=======
+Current state: [assessment]
+Test types in use: [list]
+Test types missing: [list]
+CI integration: [yes | no | partial]
+Test reliability: [stable | flaky | unknown]
+Critical paths tested: [list]
+Critical paths NOT tested: [list]
+```
+
+### test-gaps.md
+
+```
+Test Gaps
+=========
+[Gap ID]: [what is not tested]
+Priority: [highest | high | medium | lower]
+Risk: [what could go wrong]
+Recommendation: [what test to write]
+```

package/skills/09-performance/SKILL.md

@@ -0,0 +1,96 @@
+# 09-Performance Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context, architecture
+**Outputs:** performance.md, performance-findings.md
+
+---
+
+## Purpose
+
+Review the project's performance characteristics and identify bottlenecks, inefficiencies, and risks. Performance only matters where it matters — do not optimize prematurely, but do not ignore real problems.
+
+---
+
+## Process
+
+### 1. Identify performance requirements
+
+- What is the expected load?
+- What are the response time expectations?
+- What is the cost of being slow? (user experience, money, infrastructure)
+- Are there SLAs or SLOs?
+- If unknown, record "not specified" — do not assume.
+
+### 2. Identify potential bottlenecks
+
+- Database queries (N+1, missing indexes, slow queries, unbounded result sets)
+- External API calls (latency, rate limits, failure handling)
+- File operations (size, frequency, storage backend)
+- Computation (expensive operations, unbounded loops, missing caching)
+- Memory usage (leaks, large allocations, unbounded growth)
+- Network (chatty interfaces, large payloads, missing compression)
+- Concurrency (blocking operations, thread pool exhaustion, lock contention)
+- Startup time (if relevant — serverless cold start, CLI tool)
+- Background jobs (queue backlog, job duration, retry storms)
+
+### 3. Assess caching
+
+- What is cached?
+- What cache layer is used?
+- Is cache invalidation correct?
+- What happens on cache failure?
+- Are there stampedes or thundering herd risks?
+
+### 4. Assess data access patterns
+
+- How is the database accessed?
+- Are queries efficient?
+- Are indexes present where needed?
+- Are transactions used correctly?
+- Is N+1 a problem?
+- Are large queries paginated?
+
+### 5. Assess scalability
+
+- What happens when load increases?
+- Are there single points of failure?
+- Can components scale independently?
+- Are there resource limits?
+- What is the current ceiling? (if detectable)
+
+### 6. Assess cost of performance
+
+- Will optimizing this actually matter at the project's scale?
+- Is the optimization worth the complexity it adds?
+- Is there a simpler fix (index, query change, caching) before a major refactor?
+
+---
+
+## Output
+
+### performance.md
+
+```
+Performance
+===========
+Requirements: [specified | not specified]
+Expected load: [description or "unknown"]
+Bottlenecks identified: [list]
+Caching: [assessment]
+Data access: [assessment]
+Scalability: [assessment]
+```
+
+### performance-findings.md
+
+```
+Performance Findings
+====================
+[Finding ID]: [description]
+Severity: [critical | high | medium | low]
+Impact: [what it causes]
+Recommendation: [what to do]
+Evidence: [query, trace, observation]
+```

package/skills/10-audit/SKILL.md

@@ -0,0 +1,112 @@
+# 10-Audit Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context
+**Outputs:** audit-report.md, and outputs from 06, 07, 04, 03 as applicable
+
+---
+
+## Purpose
+
+Run a comprehensive audit of the project. The audit skill is a composite that runs the codebase audit, security review, architecture review, and business architecture review in sequence, then synthesizes findings into a single report.
+
+Use this skill when:
+- Taking over an existing project
+- Before a major rewrite or refactor
+- As part of due diligence
+- When a project feels "off" and you need a full picture
+- Periodically on mature projects
+
+---
+
+## Process
+
+### Phase 1: Run sub-skills in order
+
+1. **06-codebase-audit** — inspect the code
+2. **07-security** — review security posture
+3. **04-architecture** — review architecture
+4. **03-business-architecture** — understand the business
+
+The order matters. Security is run early because critical findings may stop the audit and require immediate action. Business understanding informs architecture review. Code audit informs both.
+
+### Phase 2: Synthesize
+
+Combine findings into a unified report. Identify:
+- Findings that appear across multiple domains (e.g., a security issue caused by an architectural problem)
+- The highest-risk items
+- The items that block progress
+- The items that are quick wins
+- The items that require product/business decisions
+
+### Phase 3: Prioritize
+
+Prioritize by risk and effort:
+
+| Priority | Criteria |
+|---|---|
+| P0 — Immediate | Security critical, data integrity risk, system down, legal/compliance risk |
+| P1 — High | Significant risk, blocks major work, fundamental architectural problem |
+| P2 — Medium | Notable problem, should be fixed before next release |
+| P3 — Low | Improvement, nice to have, no immediate risk |
+| P4 — Backlog | Minor, cosmetic, or long-term improvement |
+
+### Phase 4: Report
+
+Write a report that a human can act on. It should answer:
+- What is this project?
+- What is its state?
+- What are the most important findings?
+- What should be done first, and why?
+- What requires business decisions vs technical decisions?
+
+---
+
+## Output
+
+### audit-report.md
+
+```
+Audit Report
+============
+Project: [name]
+Audit date: [date]
+Auditor: [agent or person]
+Project state: [greenfield | healthy | partial | broken]
+Risk level: [low | medium | high]
+
+Summary:
+  [2-5 sentence summary of the project and its state]
+
+Findings by priority:
+  P0 — Immediate:
+    - [finding]
+  P1 — High:
+    - [finding]
+  P2 — Medium:
+    - [finding]
+  P3 — Low:
+    - [finding]
+
+Strengths:
+  - [what is good]
+
+Recommended next steps:
+  1. [action] — [reason]
+  2. ...
+
+Business decisions needed:
+  - [decision that requires product/business input]
+
+Technical decisions needed:
+  - [decision that is purely technical]
+```
+
+### Per-domain findings
+
+The audit also produces the outputs of each sub-skill:
+- `codebase-audit.md` and `code-gaps.md` (from 06)
+- `security.md` and `security-findings.md` (from 07)
+- `architecture.md` and `architecture-gaps.md` (from 04)
+- `business-model.md`, `actors.md`, etc. (from 03)

package/stacks/dotnet/SKILL.md

@@ -0,0 +1,56 @@
+# .NET 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 C# / .NET projects. Activated automatically when `*.csproj`, `*.sln`, or `.cs` files are detected.
+
+---
+
+## Conventions
+
+### Version
+
+- .NET 8 or .NET 9 are current LTS/current versions. The project's target framework is in `*.csproj`.
+- Follow the project's version.
+
+### Style
+
+- Follow the project's style configuration. Roslyn analyzers, `.editorconfig`, and formatters are the project's choice.
+- C# conventions: explicit is better than implicit. Use the type system.
+
+### Type system
+
+- C# has a static type system. Use it.
+- `var` is acceptable when the type is obvious from the assignment. Do not use it to obscure the type.
+- Records, tuples, pattern matching, and nullable reference types are features. Use them where they help.
+
+### Error handling
+
+- Use exceptions for exceptional conditions.
+- Do not swallow exceptions.
+- Consider `Result` patterns for expected failures in some codebases.
+
+### Dependencies
+
+- `*.csproj` manages dependencies. `packages.lock.json` or equivalent should be committed for applications.
+- Review NuGet packages for maintenance.
+
+### Tooling
+
+- The project's analyzers and formatters are the project's choice.
+
+---
+
+## Anti-patterns
+
+- Swallowed exceptions.
+- Overuse of `dynamic`.
+- Large classes with mixed responsibilities.
+- Ignoring nullable reference types (if enabled).