@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.
- package/AGENTS.md +204 -0
- package/LICENSE +21 -0
- package/PROMPT.md +22 -0
- package/README.md +248 -0
- package/bin/cli.js +160 -0
- package/frameworks/axum/SKILL.md +73 -0
- package/frameworks/django/SKILL.md +71 -0
- package/frameworks/fastapi/SKILL.md +73 -0
- package/frameworks/laravel/SKILL.md +67 -0
- package/frameworks/nextjs/SKILL.md +60 -0
- package/frameworks/rails/SKILL.md +78 -0
- package/frameworks/react/SKILL.md +58 -0
- package/frameworks/spring/SKILL.md +79 -0
- package/install.sh +83 -0
- package/llms.txt +26 -0
- package/package.json +47 -0
- package/skills/00-orchestrator/.gitkeep +26 -0
- package/skills/00-orchestrator/SKILL.md +368 -0
- package/skills/00-orchestrator/decision-tree.md +93 -0
- package/skills/00-orchestrator/project-detection.md +81 -0
- package/skills/00-orchestrator/skill-selection.md +87 -0
- package/skills/00-orchestrator/workflow.md +25 -0
- package/skills/01-discovery/SKILL.md +66 -0
- package/skills/02-project-context/SKILL.md +89 -0
- package/skills/03-business-architecture/SKILL.md +231 -0
- package/skills/04-architecture/SKILL.md +131 -0
- package/skills/05-documentation/SKILL.md +133 -0
- package/skills/06-codebase-audit/SKILL.md +127 -0
- package/skills/07-security/SKILL.md +159 -0
- package/skills/08-testing/SKILL.md +120 -0
- package/skills/09-performance/SKILL.md +96 -0
- package/skills/10-audit/SKILL.md +112 -0
- package/stacks/dotnet/SKILL.md +56 -0
- package/stacks/go/SKILL.md +61 -0
- package/stacks/java/SKILL.md +58 -0
- package/stacks/javascript/SKILL.md +47 -0
- package/stacks/php/SKILL.md +51 -0
- package/stacks/python/SKILL.md +52 -0
- package/stacks/ruby/SKILL.md +51 -0
- package/stacks/rust/SKILL.md +55 -0
- package/stacks/typescript/SKILL.md +55 -0
- package/templates/adr/ADR-TEMPLATE.md +64 -0
- package/templates/api-spec/API_SPEC_TEMPLATE.md +137 -0
- package/templates/architecture/ARCHITECTURE_TEMPLATE.md +81 -0
- package/templates/business-requirements/BUSINESS_REQUIREMENTS_TEMPLATE.md +77 -0
- package/templates/changelog/CHANGELOG_TEMPLATE.md +37 -0
- package/templates/database/DATABASE_TEMPLATE.md +77 -0
- package/templates/deployment/DEPLOYMENT_TEMPLATE.md +80 -0
- package/templates/project-brief/PROJECT_BRIEF_TEMPLATE.md +72 -0
- package/templates/runbook/RUNBOOK_TEMPLATE.md +54 -0
- package/templates/security/SECURITY_TEMPLATE.md +93 -0
- 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.
|