@botdigit/agent-blueprint 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/AGENTS.md +204 -0
  2. package/LICENSE +21 -0
  3. package/PROMPT.md +22 -0
  4. package/README.md +248 -0
  5. package/bin/cli.js +160 -0
  6. package/frameworks/axum/SKILL.md +73 -0
  7. package/frameworks/django/SKILL.md +71 -0
  8. package/frameworks/fastapi/SKILL.md +73 -0
  9. package/frameworks/laravel/SKILL.md +67 -0
  10. package/frameworks/nextjs/SKILL.md +60 -0
  11. package/frameworks/rails/SKILL.md +78 -0
  12. package/frameworks/react/SKILL.md +58 -0
  13. package/frameworks/spring/SKILL.md +79 -0
  14. package/install.sh +83 -0
  15. package/llms.txt +26 -0
  16. package/package.json +47 -0
  17. package/skills/00-orchestrator/.gitkeep +26 -0
  18. package/skills/00-orchestrator/SKILL.md +368 -0
  19. package/skills/00-orchestrator/decision-tree.md +93 -0
  20. package/skills/00-orchestrator/project-detection.md +81 -0
  21. package/skills/00-orchestrator/skill-selection.md +87 -0
  22. package/skills/00-orchestrator/workflow.md +25 -0
  23. package/skills/01-discovery/SKILL.md +66 -0
  24. package/skills/02-project-context/SKILL.md +89 -0
  25. package/skills/03-business-architecture/SKILL.md +231 -0
  26. package/skills/04-architecture/SKILL.md +131 -0
  27. package/skills/05-documentation/SKILL.md +133 -0
  28. package/skills/06-codebase-audit/SKILL.md +127 -0
  29. package/skills/07-security/SKILL.md +159 -0
  30. package/skills/08-testing/SKILL.md +120 -0
  31. package/skills/09-performance/SKILL.md +96 -0
  32. package/skills/10-audit/SKILL.md +112 -0
  33. package/stacks/dotnet/SKILL.md +56 -0
  34. package/stacks/go/SKILL.md +61 -0
  35. package/stacks/java/SKILL.md +58 -0
  36. package/stacks/javascript/SKILL.md +47 -0
  37. package/stacks/php/SKILL.md +51 -0
  38. package/stacks/python/SKILL.md +52 -0
  39. package/stacks/ruby/SKILL.md +51 -0
  40. package/stacks/rust/SKILL.md +55 -0
  41. package/stacks/typescript/SKILL.md +55 -0
  42. package/templates/adr/ADR-TEMPLATE.md +64 -0
  43. package/templates/api-spec/API_SPEC_TEMPLATE.md +137 -0
  44. package/templates/architecture/ARCHITECTURE_TEMPLATE.md +81 -0
  45. package/templates/business-requirements/BUSINESS_REQUIREMENTS_TEMPLATE.md +77 -0
  46. package/templates/changelog/CHANGELOG_TEMPLATE.md +37 -0
  47. package/templates/database/DATABASE_TEMPLATE.md +77 -0
  48. package/templates/deployment/DEPLOYMENT_TEMPLATE.md +80 -0
  49. package/templates/project-brief/PROJECT_BRIEF_TEMPLATE.md +72 -0
  50. package/templates/runbook/RUNBOOK_TEMPLATE.md +54 -0
  51. package/templates/security/SECURITY_TEMPLATE.md +93 -0
  52. package/templates/testing/TESTING_TEMPLATE.md +87 -0
@@ -0,0 +1,73 @@
1
+ # Axum Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/rust
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Axum projects. Activated when Axum is detected in a Rust project.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Axum is an ergonomic, composable Rust web framework built on Tokio and Tower. Understand:
19
+ - **Routers** — route composition and nesting
20
+ - **Handlers** — async functions or `State` extractors
21
+ - **Extractors** — how request data is extracted (JSON, form, headers, path, state)
22
+ - **Middlewares** — Tower middleware stack
23
+ - **State** — shared application state
24
+ - **Error handling** — `Result`, `IntoResponse`, custom error types
25
+
26
+ ---
27
+
28
+ ## Conventions
29
+
30
+ ### Handlers and extractors
31
+
32
+ - Handlers should be focused. A handler that does too much is a sign that logic should be extracted.
33
+ - Use extractors for request data. Do not manually parse requests when extractors can do it.
34
+ - Pydantic... err, the Rust equivalent: use serde for serialization. Validate input at the boundary.
35
+
36
+ ### State management
37
+
38
+ - Axum's `State` extractor shares application state. Understand what the project puts in state.
39
+ - State should be shared safely (Arc, Mutex, RwLock, or similar). Understand the project's choice.
40
+ - Do not put mutable state in handlers without synchronization.
41
+
42
+ ### Error handling
43
+
44
+ - Use `Result` with custom error types that implement `IntoResponse`.
45
+ - Errors should be informative to the client (within security limits) and to the logs.
46
+ - Do not expose internal error details to clients.
47
+
48
+ ### Middleware
49
+
50
+ - Tower middleware is the mechanism. Use it for cross-cutting concerns.
51
+ - Do not put business logic in middleware.
52
+
53
+ ### Database
54
+
55
+ - The project's database choice is its own (SQLx, Diesel, SeaORM, or similar).
56
+ - Understand how the project manages connections (pool, state, or other).
57
+ - Migrations are the source of truth for schema.
58
+
59
+ ### Testing
60
+
61
+ - Axum provides `TestClient` (via `axum::testing` or similar). Use it for integration tests.
62
+ - Use tokio's test macros for async tests.
63
+ - Test business logic, API endpoints, and critical flows.
64
+
65
+ ---
66
+
67
+ ## Anti-patterns
68
+
69
+ - Business logic in handlers.
70
+ - Ignoring error handling (unwrap in handlers).
71
+ - Shared mutable state without synchronization.
72
+ - Hardcoded secrets in source code.
73
+ - Not using extractors when they apply.
@@ -0,0 +1,71 @@
1
+ # Django Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/python
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Django projects. Activated when Django structure is detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Django is a "batteries included" framework. Understand what the project uses:
19
+ - **MVT** — models, views, templates
20
+ - **Class-based views** vs **function-based views**
21
+ - **REST framework** — if the project is an API
22
+ - **DRF serializers** — API data shaping
23
+ - **Admin** — Django's admin interface (customized or stock)
24
+ - **Signals** — event hooks (use sparingly)
25
+ - **Middleware** — cross-cutting concerns
26
+ - **Celery / Django Q / similar** — background tasks
27
+ - **ORM** — Django's ORM is central
28
+
29
+ ---
30
+
31
+ ## Conventions
32
+
33
+ ### Models and the ORM
34
+
35
+ - Models are the heart of a Django project. Understand the project's models, relationships, and constraints.
36
+ - The ORM is powerful. Understand query evaluation to avoid N+1 and unnecessary queries.
37
+ - Migrations are the source of truth for schema. Do not edit the database outside of migrations.
38
+ - Model methods and properties are good places for model-specific logic. Business logic that spans models belongs elsewhere.
39
+
40
+ ### Views
41
+
42
+ - Views handle request → response. They should not contain business logic that belongs in models, services, or forms.
43
+ - Form handling: use Django forms or the project's chosen form library. Validation belongs with the form or serializer.
44
+ - Class-based views provide structure. If the project uses them, understand the lifecycle. If it uses function-based views, follow that convention.
45
+
46
+ ### API design (if DRF)
47
+
48
+ - Serializers define the API contract. Understand what each serializer does.
49
+ - ViewSets and routers provide convention. Follow the project's pattern.
50
+ - Authentication and permission classes are the place for access control.
51
+
52
+ ### Settings
53
+
54
+ - Django settings are significant. Understand the project's settings structure (single file, split by environment, django-configurations, or similar).
55
+ - Secrets in settings: the project should use environment variables, not hardcoded values.
56
+
57
+ ### Testing
58
+
59
+ - Django has a strong testing framework. Use it.
60
+ - The `TestCase` class provides database isolation. Use it for tests that touch the database.
61
+ - Test business logic, API endpoints, and critical flows.
62
+
63
+ ---
64
+
65
+ ## Anti-patterns
66
+
67
+ - Business logic in views.
68
+ - N+1 queries from unfiltered related object access.
69
+ - Using signals for core business logic (signals hide control flow).
70
+ - Editing the database directly instead of writing migrations.
71
+ - Hardcoded secrets in settings files.
@@ -0,0 +1,73 @@
1
+ # FastAPI Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/python
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with FastAPI projects. Activated when FastAPI is detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ FastAPI is a modern, async-first Python framework. Understand:
19
+ - **Path operations** — the endpoint handlers
20
+ - **Dependency injection** — FastAPI's DI system
21
+ - **Pydantic models** — request/response validation and serialization
22
+ - **Async/await** — the project's async usage
23
+ - **Background tasks** — if used
24
+ - **Database integration** — SQLAlchemy, SQLModel, Tortoise, or similar
25
+
26
+ ---
27
+
28
+ ## Conventions
29
+
30
+ ### Pydantic models
31
+
32
+ - Pydantic models define the API contract. They are the source of truth for request and response shapes.
33
+ - Use them for validation. Do not manually validate input that Pydantic can validate.
34
+ - Models should be meaningful, not just `BaseModel` with arbitrary fields.
35
+
36
+ ### Dependency injection
37
+
38
+ - FastAPI's DI is a feature. Use it for shared logic (auth, database session, current user).
39
+ - Dependencies should be well-defined. Avoid hidden dependencies.
40
+
41
+ ### Async
42
+
43
+ - FastAPI supports async path operations. Use async where it helps (I/O-bound operations).
44
+ - Async is not magic. A slow synchronous operation in an async handler blocks the event loop.
45
+ - Understand which database drivers and libraries are async-compatible before making everything async.
46
+
47
+ ### Error handling
48
+
49
+ - Use HTTPException for HTTP errors.
50
+ - Use custom exception handlers for application-specific errors where appropriate.
51
+ - Do not expose internal errors to clients.
52
+
53
+ ### Database
54
+
55
+ - The project's database integration is its choice. Understand it.
56
+ - Migrations (Alembic or similar) are the source of truth for schema.
57
+ - Connection management: understand how the project manages database sessions (dependency, context manager, or other).
58
+
59
+ ### Testing
60
+
61
+ - FastAPI provides a `TestClient`. Use it for integration tests.
62
+ - The project may use pytest or similar. Follow the project's choice.
63
+ - Test business logic, API endpoints, and critical flows.
64
+
65
+ ---
66
+
67
+ ## Anti-patterns
68
+
69
+ - Putting business logic in path operation functions.
70
+ - Ignoring Pydantic validation and doing manual validation.
71
+ - Mixing sync and async without understanding the implications.
72
+ - Hardcoded secrets in the application code.
73
+ - Returning raw database models as API responses without a defined contract.
@@ -0,0 +1,67 @@
1
+ # Laravel Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/php
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Laravel projects. Activated when Laravel structure is detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Laravel is a full-stack framework with conventions. Understand what the project uses:
19
+ - **MVC** — controllers, models, views (Blade or Inertia or API)
20
+ - **API-only** — resource/controllers, no views
21
+ - **Inertia** — SPA with server-side routing
22
+ - **Livewire** — dynamic interfaces without full SPA
23
+ - **Queue workers** — background processing
24
+ - **Events / Listeners** — event-driven architecture
25
+ - **Jobs / Scheduled tasks** — async and cron
26
+
27
+ ---
28
+
29
+ ## Conventions
30
+
31
+ ### Eloquent and the database
32
+
33
+ - Eloquent is an ORM. Understand the project's models, relationships, and scopes.
34
+ - N+1 queries are a common problem. Use eager loading where appropriate.
35
+ - Migrations are the source of truth for schema. Do not edit the database directly in a way that diverges from migrations.
36
+ - Seeders and factories are for test data and development. Do not rely on them for production data.
37
+
38
+ ### Controllers
39
+
40
+ - Controllers should be thin. Business logic belongs in models, services, actions, or similar — matching the project's convention.
41
+ - If the project uses Form Requests for validation, use them. Do not validate in the controller body if Form Requests exist.
42
+
43
+ ### Service layer
44
+
45
+ - If the project has a service layer, use it. If it does not, understand why before adding one.
46
+ - Do not add a service layer because "that's what frameworks do." Add it if the project needs it.
47
+
48
+ ### Middleware
49
+
50
+ - Middleware is for cross-cutting concerns (auth, logging, CORS). Use it for those.
51
+ - Do not put business logic in middleware.
52
+
53
+ ### Testing
54
+
55
+ - Laravel has a testing framework built in. Use it.
56
+ - The project may use Pest or PHPUnit. Follow the project's choice.
57
+ - Test the behavior that matters: business rules, API endpoints, critical user flows.
58
+
59
+ ---
60
+
61
+ ## Anti-patterns
62
+
63
+ - Fat controllers with business logic.
64
+ - N+1 queries from lazy loading in loops.
65
+ - Putting business logic in routes files.
66
+ - Ignoring migrations and editing the database directly.
67
+ - Using `DB::raw` where Eloquent would do, without understanding the SQL injection risk.
@@ -0,0 +1,60 @@
1
+ # Next.js Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/typescript or stacks/javascript
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Next.js projects. Activated when `next.config` and Next.js project structure are detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Next.js provides several rendering strategies. Understand which the project uses:
19
+ - **SSR** (Server-Side Rendering) — `getServerSideProps` or Server Components
20
+ - **SSG** (Static Site Generation) — `getStaticProps` or static Server Components
21
+ - **ISR** (Incremental Static Regeneration)
22
+ - **Client Components** — `'use client'`
23
+ - **API Routes** — `app/api/` or `pages/api/`
24
+ - **Server Actions** — if used
25
+
26
+ The rendering strategy affects data flow, caching, and architectural decisions. Understand the project's choice before modifying.
27
+
28
+ ---
29
+
30
+ ## Conventions
31
+
32
+ ### App Router vs Pages Router
33
+
34
+ - The project uses one or the other. Follow it. Do not mix unless the migration is explicit and documented.
35
+ - App Router is the current direction. Pages Router is still valid for existing projects.
36
+
37
+ ### Server vs Client components
38
+
39
+ - Server Components are the default in App Router. Use Client Components where interactivity requires it.
40
+ - Do not make everything a Client Component "because it's easier." Understand the boundary.
41
+
42
+ ### Data fetching
43
+
44
+ - Data fetching strategy (server-side, client-side, hybrid) is an architectural decision. Understand what the project does and why.
45
+ - Caching behavior in Next.js is specific. Understand it before changing data fetching.
46
+
47
+ ### Environment variables
48
+
49
+ - Next.js has specific environment variable conventions (`NEXT_PUBLIC_` for client exposure).
50
+ - Do not expose secrets to the client. Next.js makes this explicit with the `NEXT_PUBLIC_` prefix. Respect it.
51
+
52
+ ---
53
+
54
+ ## Anti-patterns
55
+
56
+ - Making all components Client Components.
57
+ - Mixing App Router and Pages Router without a migration plan.
58
+ - Exposing secrets via `NEXT_PUBLIC_` variables.
59
+ - Fetching data on every render without caching strategy.
60
+ - Putting business logic in components instead of server functions or services.
@@ -0,0 +1,78 @@
1
+ # Ruby on Rails Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/ruby
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Ruby on Rails projects. Activated when Rails is detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Rails is an opinionated MVC framework. Understand what the project uses:
19
+ - **MVC** — models, controllers, views
20
+ - **ActiveRecord** — the ORM
21
+ - **Routes** — `config/routes.rb`
22
+ - **Mailers** — email delivery
23
+ - **Jobs** — Active Job and the backend (Sidekiq, Resque, etc.)
24
+ - **Assets** — the asset pipeline or import maps or a JS bundler
25
+ - **API mode** — if the project is API-only
26
+
27
+ ---
28
+
29
+ ## Conventions
30
+
31
+ ### ActiveRecord and the database
32
+
33
+ - ActiveRecord models are central. Understand the project's models, associations, validations, and scopes.
34
+ - Migrations are the source of truth for schema. Do not edit the database outside of migrations.
35
+ - N+1 queries are common. Use `includes`, `preload`, or `eager_load` where appropriate.
36
+ - Callbacks are powerful and can hide control flow. Understand the project's use of them. Overuse of callbacks is a common Rails problem.
37
+
38
+ ### Controllers
39
+
40
+ - Controllers should be thin. They handle request/response, not business logic.
41
+ - Strong parameters are the mechanism for permitted input. Use them.
42
+ - Before actions are for cross-cutting controller concerns. Do not put business logic in them.
43
+
44
+ ### Business logic placement
45
+
46
+ - Rails does not enforce where business logic lives. The project's convention is what matters.
47
+ - Common patterns: models, service objects, interactors, commands, queries. Follow the project's convention.
48
+ - Do not introduce a pattern the project does not use without a reason.
49
+
50
+ ### Views
51
+
52
+ - Views should present data, not compute it.
53
+ - Helpers are for presentation logic that is reused across views.
54
+ - Partials are for reusable view fragments.
55
+
56
+ ### Background jobs
57
+
58
+ - Active Job is the abstraction. The backend (Sidekiq, Resque, etc.) is the implementation.
59
+ - Understand the project's job infrastructure before adding or modifying jobs.
60
+ - Jobs should be idempotent where possible.
61
+
62
+ ### Testing
63
+
64
+ - Rails has a testing framework built in. Use it.
65
+ - The project may use RSpec, Minitest, or similar. Follow the project's choice.
66
+ - Test business logic, controllers, models where appropriate, and critical flows.
67
+ - Factory bot or similar for test data. Follow the project's choice.
68
+
69
+ ---
70
+
71
+ ## Anti-patterns
72
+
73
+ - Fat controllers with business logic.
74
+ - Fat models with unrelated responsibilities.
75
+ - Callbacks that do more than they appear to do.
76
+ - N+1 queries.
77
+ - Editing the database directly instead of migrations.
78
+ - Hardcoded secrets in credentials or source.
@@ -0,0 +1,58 @@
1
+ # React Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/typescript or stacks/javascript
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with React projects (SPA or library usage). Activated when React is detected without Next.js.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ - Is this a SPA (single-page application) with client-side routing?
19
+ - Is it embedded in a larger application (micro-frontend, widget)?
20
+ - Is it using a state management library? Which one? (Redux, Zustand, Jotai, Context, MobX, or none)
21
+ - Is it using a routing library? Which one?
22
+ - Is it server-rendered at all, or purely client-side?
23
+
24
+ ---
25
+
26
+ ## Conventions
27
+
28
+ ### Component design
29
+
30
+ - Components should be focused. A component that does too much is a sign that it should be split.
31
+ - Custom hooks extract behavior. If a component has logic that could be reused, consider a hook.
32
+ - Props should be as specific as practical. Avoid passing large objects when specific values would do.
33
+
34
+ ### State management
35
+
36
+ - Start simple. Local state, then context, then a state library if there is a real need.
37
+ - Not everything needs to be in a global store. State that is only used in one component tree should stay there.
38
+
39
+ ### Data flow
40
+
41
+ - Data flows down. Events flow up. This is the React model. Respect it.
42
+ - Avoid mutating props.
43
+ - If data is shared across distant components, understand why before choosing a solution.
44
+
45
+ ### Effects
46
+
47
+ - `useEffect` is for side effects, not for derived state. If you can compute a value during render, do that instead.
48
+ - Effect dependencies should be correct. Missing dependencies cause bugs. Unnecessary dependencies cause re-renders.
49
+
50
+ ---
51
+
52
+ ## Anti-patterns
53
+
54
+ - Putting business logic in UI components.
55
+ - Using effect for everything.
56
+ - Prop drilling without considering context or component restructuring.
57
+ - Global state for everything.
58
+ - Uncontrolled components where controlled would be clearer (or vice versa, depending on the actual need).
@@ -0,0 +1,79 @@
1
+ # Spring Boot Framework Skill
2
+
3
+ **Version:** 1.0.0
4
+ **Compatible:** project_skills >= 1.0
5
+ **Requires:** stacks/java
6
+ **Outputs:** (none — guidance only)
7
+
8
+ ---
9
+
10
+ ## Purpose
11
+
12
+ Guidance for working with Spring Boot projects. Activated when Spring Boot is detected.
13
+
14
+ ---
15
+
16
+ ## Architecture understanding
17
+
18
+ Spring Boot is a convention-driven Java framework. Understand:
19
+ - ** layered architecture** — controllers, services, repositories
20
+ - **Dependency injection** — Spring's IoC container
21
+ - **Spring Data** — JPA, JDBC, MongoDB, or other repositories
22
+ - **REST controllers** — `@RestController`, `@RequestMapping`
23
+ - **Security** — Spring Security configuration
24
+ - **Transactions** — `@Transactional`
25
+ - **Async** — `@Async`, task executors
26
+ - **Configuration** — `application.properties` / `application.yml`, profiles
27
+
28
+ ---
29
+
30
+ ## Conventions
31
+
32
+ ### Layered architecture
33
+
34
+ - Controllers handle HTTP. Services handle business logic. Repositories handle data access.
35
+ - This is the conventional Spring layout. Follow it unless the project has a documented alternative.
36
+ - Do not put business logic in controllers. Do not put HTTP concerns in services.
37
+
38
+ ### Dependency injection
39
+
40
+ - Spring's DI is central. Understand the project's bean configuration (component scanning, explicit beans, or both).
41
+ - Constructor injection is preferred over field injection. Follow the project's convention.
42
+ - Beans have a lifecycle. Understand the scope of the beans you use.
43
+
44
+ ### Data access
45
+
46
+ - Spring Data repositories provide a convention. Understand what the project uses (JpaRepository, CrudRepository, custom repositories, or raw JPA).
47
+ - `@Transactional` boundaries matter. Understand where transactions start and end.
48
+ - N+1 queries are possible with JPA. Understand the project's fetch strategy.
49
+ - Migrations: Flyway or Liquibase are common. If the project uses them, follow them. If it does not, note that as a gap.
50
+
51
+ ### REST API design
52
+
53
+ - `@RestController` and `@RequestMapping` define the API.
54
+ - DTOs (Data Transfer Objects) are common for API contracts. Understand the project's approach (DTOs, records, or direct entity exposure).
55
+ - Validation: Bean Validation (JSR-380) is the standard. Use it for input validation.
56
+ - Error handling: `@ControllerAdvice` and `@ExceptionHandler` are the conventional mechanism.
57
+
58
+ ### Security
59
+
60
+ - Spring Security is powerful and can be complex. Understand the project's security configuration.
61
+ - Authentication and authorization are configured in Security configuration. Understand how.
62
+ - Do not rely on security by obscurity. Configure explicit access rules.
63
+
64
+ ### Testing
65
+
66
+ - Spring Boot provides test support (`@SpringBootTest`, `@DataJpaTest`, `@WebMvcTest`, and similar).
67
+ - Use the right slice for the right test. A repository test does not need the full application context.
68
+ - JUnit 5 is the standard. The project may use AssertJ, Mockito, or similar. Follow the project's choice.
69
+
70
+ ---
71
+
72
+ ## Anti-patterns
73
+
74
+ - Business logic in controllers.
75
+ - Field injection everywhere (hard to test, hides dependencies).
76
+ - Bidirectional entity relationships without understanding the consequences.
77
+ - Ignoring transaction boundaries.
78
+ - Exposing entities directly as API responses without a deliberate choice.
79
+ - Hardcoded secrets in configuration files.
package/install.sh ADDED
@@ -0,0 +1,83 @@
1
+ #!/usr/bin/env bash
2
+ # ==============================================================================
3
+ # Agent Blueprint — Universal AI Agent Skills Installer & Project Linker
4
+ # Can be run locally OR remotely via:
5
+ # curl -fsSL https://raw.githubusercontent.com/botdigit-official/agent-blueprint/main/install.sh | bash
6
+ # ==============================================================================
7
+
8
+ set -euo pipefail
9
+
10
+ REPO_URL="https://github.com/botdigit-official/agent-blueprint.git"
11
+ GLOBAL_CACHE_DIR="${HOME}/.agent-blueprint"
12
+ TARGET_DIR="${1:-.}"
13
+
14
+ echo "====================================================="
15
+ echo " 📐 Agent Blueprint — AI Agent Skills Installer"
16
+ echo " Standardizing Living Docs & Architectural Rigor"
17
+ echo "====================================================="
18
+
19
+ TARGET_FULL_PATH="$(cd "$TARGET_DIR" 2>/dev/null && pwd || pwd)"
20
+
21
+ # Step 1: Ensure we have the latest Agent Blueprint source via git clone / pull
22
+ if [ -d "$GLOBAL_CACHE_DIR/.git" ]; then
23
+ echo "🔄 Pulling latest Agent Blueprint skills from GitHub..."
24
+ (cd "$GLOBAL_CACHE_DIR" && git pull --quiet origin main 2>/dev/null || git pull --quiet origin master 2>/dev/null || true)
25
+ else
26
+ echo "📥 Cloning Agent Blueprint from GitHub ($REPO_URL)..."
27
+ mkdir -p "$GLOBAL_CACHE_DIR"
28
+ git clone --depth 1 "$REPO_URL" "$GLOBAL_CACHE_DIR" --quiet
29
+ fi
30
+
31
+ BLUEPRINT_ROOT="$GLOBAL_CACHE_DIR"
32
+
33
+ echo "📂 Source Blueprint: $BLUEPRINT_ROOT"
34
+ echo "🎯 Target Project: $TARGET_FULL_PATH"
35
+
36
+ DEST_AGENTS_DIR="$TARGET_FULL_PATH/.agents"
37
+ DEST_SKILLS_DIR="$DEST_AGENTS_DIR/skills"
38
+
39
+ mkdir -p "$DEST_SKILLS_DIR"
40
+
41
+ # Link or copy AGENTS.md entry point
42
+ if [ ! -f "$TARGET_FULL_PATH/AGENTS.md" ]; then
43
+ cp "$BLUEPRINT_ROOT/AGENTS.md" "$TARGET_FULL_PATH/AGENTS.md"
44
+ echo "📄 Created AGENTS.md at project root"
45
+ fi
46
+
47
+ # Link all modular skills
48
+ for skill_path in "$BLUEPRINT_ROOT/skills"/*; do
49
+ if [ -d "$skill_path" ]; then
50
+ skill_name="$(basename "$skill_path")"
51
+ rm -rf "$DEST_SKILLS_DIR/$skill_name"
52
+ ln -s "$skill_path" "$DEST_SKILLS_DIR/$skill_name"
53
+ fi
54
+ done
55
+
56
+ # Create a local helper script in the project for easy updating
57
+ cat << 'EOF' > "$TARGET_FULL_PATH/blueprint"
58
+ #!/usr/bin/env bash
59
+ set -e
60
+ CACHE="${HOME}/.agent-blueprint"
61
+ if [ "$1" = "update" ]; then
62
+ echo "🔄 Updating Agent Blueprint skills from GitHub..."
63
+ (cd "$CACHE" && git pull origin main)
64
+ echo "✅ Skills updated to latest version."
65
+ elif [ "$1" = "audit" ]; then
66
+ echo "🔍 Starting Agent Blueprint discovery & audit..."
67
+ echo "👉 Prompt your agent: 'Read AGENTS.md and start audit (skills/10-audit)'"
68
+ elif [ "$1" = "status" ]; then
69
+ echo "📐 Agent Blueprint installed at: .agents/skills"
70
+ (cd "$CACHE" && git log -1 --oneline)
71
+ else
72
+ echo "Usage: ./blueprint [update | audit | status]"
73
+ fi
74
+ EOF
75
+ chmod +x "$TARGET_FULL_PATH/blueprint"
76
+
77
+ echo ""
78
+ echo "✅ Agent Blueprint successfully installed in $TARGET_FULL_PATH!"
79
+ echo " - Skills directory: .agents/skills/"
80
+ echo " - Agent manual: AGENTS.md"
81
+ echo " - Helper CLI: ./blueprint [update | audit | status]"
82
+ echo ""
83
+ echo "🎉 Prompt your agent: 'Read AGENTS.md and start project discovery'."
package/llms.txt ADDED
@@ -0,0 +1,26 @@
1
+ # Agent Blueprint
2
+
3
+ > The universal blueprint and skill standard for AI coding agents — teaching LLMs how to think, audit, architect, and properly document any software project.
4
+
5
+ ## Core Rules for LLMs
6
+ - The agent must adapt to the project. The project must not be forced to adapt to the skill.
7
+ - Inspect before assuming. Understand existing architecture, dependencies, and state machines before editing.
8
+ - Business logic comes before code structure. Security and data integrity come before features.
9
+ - Deterministic tools before AI. Use AI only where reasoning adds unique value.
10
+ - Never rewrite working systems unnecessarily. Preserve existing functionality unless explicitly deprecated.
11
+ - Every architectural decision needs an Architectural Decision Record (ADR).
12
+ - Every major change needs automated tests and must update living documentation in docs/.
13
+
14
+ ## Key Documents
15
+ - [AGENTS.md](AGENTS.md): Entry point and complete execution lifecycle for AI coding agents.
16
+ - [Orchestrator](skills/00-orchestrator/SKILL.md): Project classification, technology detection, and skill activation.
17
+ - [Discovery](skills/01-discovery/SKILL.md): Locating projects in monorepos or nested directories.
18
+ - [Project Context](skills/02-project-context/SKILL.md): Inspecting frameworks, languages, databases, and dependencies.
19
+ - [Business Architecture](skills/03-business-architecture/SKILL.md): Domain modeling, actor definitions, workflows, and state machines.
20
+ - [Architecture](skills/04-architecture/SKILL.md): System boundaries, modular monoliths, and ADR templates.
21
+ - [Documentation Standard](skills/05-documentation/SKILL.md): Living documentation framework (docs/ hierarchy).
22
+ - [Codebase Audit](skills/06-codebase-audit/SKILL.md): Static code hygiene, patterns, and debt discovery.
23
+ - [Security](skills/07-security/SKILL.md): Defense-in-depth, cryptographic hashing, CSRF, and rate limiting.
24
+ - [Testing](skills/08-testing/SKILL.md): Test strategy, regression suites, and verification matrix.
25
+ - [Performance](skills/09-performance/SKILL.md): Query optimization, caching, latency profiling.
26
+ - [Full Audit](skills/10-audit/SKILL.md): Combined forensic audit workflow.