@botdigit/agent-blueprint 1.0.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@botdigit/agent-blueprint",
+  "version": "1.0.0",
+  "description": "The universal blueprint and skill standard for AI coding agents — teaching agents how to think, audit, architect, and properly document any software project.",
+  "main": "bin/cli.js",
+  "bin": "./bin/cli.js",
+  "files": [
+    "bin",
+    "skills",
+    "stacks",
+    "frameworks",
+    "templates",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "install.sh",
+    "llms.txt",
+    "PROMPT.md"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js status"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botdigit-official/agent-blueprint.git"
+  },
+  "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "agentic-workflows",
+    "cursor",
+    "claude-code",
+    "antigravity",
+    "windsurf",
+    "developer-tools",
+    "prompt-engineering",
+    "software-architecture",
+    "code-audit",
+    "documentation"
+  ],
+  "author": "BotDigit (https://botdigit.com)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/botdigit-official/agent-blueprint/issues"
+  },
+  "homepage": "https://github.com/botdigit-official/agent-blueprint#readme"
+}

package/skills/00-orchestrator/.gitkeep

@@ -0,0 +1,26 @@
+cd ./ProjectSkillsOS && git init && git add -A && git commit -m "$(cat <<'COMMIT_EOF'
+Initialize Project Skills OS v1.0
+
+Core philosophy, architecture, and 10 foundational skills:
+- 00-orchestrator (triage, detect, select)
+- 01-discovery (locate project)
+- 02-project-context (detect stack)
+- 03-business-architecture (domain, actors, rules, flows)
+- 04-architecture (review, ADR, gaps)
+- 05-documentation (living docs standard)
+- 06-codebase-audit (code inspection)
+- 07-security (security review)
+- 08-testing (test strategy)
+- 09-performance (performance review)
+- 10-audit (combined audit workflow)
+
+Stack adapters: javascript, typescript, python, php, rust, go, java, ruby, dotnet
+Framework adapters: nextjs, react, laravel, django, fastapi, axum, rails, spring
+Templates: ADR, project-brief, business-requirements, architecture, database, security, testing, deployment, runbook, changelog
+Examples: botdigit-site, saas, marketplace, ecommerce, fintech, directory, mobile-app, ai-product, internal-tool
+
+The agent must adapt to the project. The project must not be forced to adapt to the skill.
+
+Co-Authored-By: Codebuff <noreply@codebuff.com>
+COMMIT_EOF
+)"

package/skills/00-orchestrator/SKILL.md

@@ -0,0 +1,368 @@
+# 00-Orchestrator Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery
+**Outputs:** selected-skills.md, project-classification.md
+
+---
+
+## Purpose
+
+The orchestrator is the entry point and decision engine for all agent work on a project. It:
+
+1. Classifies the project state (greenfield / healthy / partial / broken)
+2. Detects the technology stack automatically
+3. Detects the project type and business domain
+4. Selects the minimum applicable skill set
+5. Establishes the workflow for the current task
+
+Every agent session starts here.
+
+---
+
+## Core Principle
+
+**Do not select skills by assumption. Select skills by detection.**
+
+Never say "this is a Laravel project, use the Laravel skill." Instead:
+
+1. Inspect `composer.json`, `artisan`, `app/`, `config/` — confirm it is Laravel
+2. Confirm the Laravel version
+3. Activate the Laravel adapter
+4. Also activate any other detected technologies
+
+---
+
+## Workflow
+
+### Phase 1: Project State Classification
+
+```
+                ┌─────────────────────────┐
+                │   Is there existing     │
+                │   code in the project?  │
+                └────────────┬────────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │ YES                          │ NO
+              ▼                              ▼
+   ┌───────────────────┐        ┌───────────────────┐
+   │ Is the code       │        │ Greenfield        │
+   │ healthy, partial, │        │ Workflow          │
+   │ or broken?        │        │                   │
+   └────────┬──────────┘        │ 1. Establish      │
+            │                    │    foundations    │
+    ┌──────┼──────┐             │ 2. Choose         │
+    │      │      │             │    architecture   │
+    ▼      ▼      ▼             │ 3. Set up docs    │
+   Healthy Partial Broken       │ 4. Plan first     │
+    │      │      │             │    increment      │
+    ▼      ▼      ▼             └───────────────────┘
+   Improve Reconcile Stabilize
+```
+
+#### Healthy
+
+- Code is functional and reasonably structured
+- Approach: improve incrementally
+- Preserve existing patterns
+- Add tests for new changes
+- Document as you go
+- **Skills:** codebase-audit (light), architecture (if changes affect architecture), security (if applicable), testing, [stack], [framework]
+
+#### Partial
+
+- Code exists but is incomplete, inconsistent, or ambiguous
+- Approach: reconcile before redesign
+- Map what exists to what is intended
+- Identify gaps between implementation and intent
+- Do not rewrite working parts
+- **Skills:** codebase-audit (full), architecture, business-architecture, documentation, [stack], [framework]
+
+#### Broken
+
+- Code exists but has fundamental problems (security, data integrity, architectural contradictions)
+- Approach: stabilize first
+- Fix highest-risk issues immediately
+- Document problems and fixes as you go
+- Do not introduce new features until stable
+- **Skills:** security (first), codebase-audit (full), architecture, business-architecture, documentation, [stack], [framework], testing
+
+### Phase 2: Technology Detection
+
+Inspect these files and directories. Record what you find.
+
+#### Programming Language
+
+| Signal | Language | Confidence |
+|---|---|---|
+| `Cargo.toml` + `src/main.rs` or `src/lib.rs` | Rust | High |
+| `go.mod` + `.go` files | Go | High |
+| `pom.xml` or `build.gradle` + `.java` files | Java | High |
+| `Gemfile` + `.rb` files | Ruby | High |
+| `*.csproj` or `*.sln` + `.cs` files | C# / .NET | High |
+| `composer.json` + `vendor/` or `artisan` | PHP | High |
+| `package.json` + `.ts` files | TypeScript | High |
+| `package.json` + `.js` files | JavaScript | High |
+| `pyproject.toml` or `requirements.txt` or `setup.py` + `.py` files | Python | High |
+| `index.html` + `.css` only | Static site | High |
+
+#### Framework
+
+| Signal | Framework | Confidence |
+|---|---|---|
+| `next.config` + `app/` or `pages/` + `package.json` (next) | Next.js | High |
+| `react` in `package.json` + components + no next config | React (SPA) | High |
+| `artisan` + `app/Http/` + `config/` + `resources/views/` | Laravel | High |
+| `manage.py` + `django` in `requirements` + `settings.py` | Django | High |
+| `fastapi` or `starlette` in imports + `main.py` with `FastAPI()` | FastAPI | High |
+| `axum` or `tokio` in `Cargo.toml` + `router` | Axum (Rust) | High |
+| `rails` command + `app/controllers/` + `config/routes.rb` | Ruby on Rails | High |
+| `spring` in `pom.xml`/`build.gradle` + `@RestController` | Spring Boot | High |
+
+#### Database
+
+| Signal | Database | Confidence |
+|---|---|---|
+| `postgresql` or `postgres` in config | PostgreSQL | High |
+| `mysql` or `mariadb` in config | MySQL / MariaDB | High |
+| `sqlite` in config or `.sqlite` / `.db` files | SQLite | High |
+| `mongo` in config or `mongoose`/`mongodb` imports | MongoDB | High |
+| `redis` in config or `redis://` URLs | Redis | High |
+| `prisma.schema` or `schema.prisma` | Prisma (ORM, reveals DB) | High |
+| `migrations/` or `db/migrate/` or `flyway/` | Migration system (reveals DB) | Medium |
+| `models/` with ORM imports | ORM in use (reveals DB) | Medium |
+
+#### Infrastructure
+
+| Signal | Infrastructure | Confidence |
+|---|---|---|
+| `Dockerfile` | Docker | High |
+| `docker-compose.yml` or `docker-compose.yaml` | Docker Compose | High |
+| `terraform/` or `.tf` files | Terraform | High |
+| `k8s/`, `kubernetes/`, or `*.yaml` with `Deployment` | Kubernetes | Medium |
+| `vercel.json` or `vercel` in CI | Vercel | High |
+| `.github/workflows/` with deploy steps | GitHub Actions CI/CD | High |
+| `netlify.toml` or `netlify` in CI | Netlify | High |
+| `cloudflare` mentions | Cloudflare | Medium |
+| `nginx` config or `nginx.conf` | Nginx | High |
+| `rails`, `artisan`, `manage.py` with server commands | Built-in dev server | Medium |
+
+#### Project Type
+
+| Signal | Project Type | Confidence |
+|---|---|---|
+| `payment`, `billing`, `subscription`, `stripe`, `pricing` | SaaS / Commercial | Medium |
+| `marketplace`, `seller`, `buyer`, `listing`, `escrow` | Marketplace | Medium |
+| `product`, `cart`, `checkout`, `inventory` | E-commerce | Medium |
+| `bank`, `account`, `transaction`, `ledger`, `compliance` | Fintech | Medium |
+| `directory`, `listing`, `search`, `category` | Directory | Medium |
+| `auth`, `login`, `session`, `oauth`, `jwt` | Auth system | Medium |
+| `admin`, `dashboard`, `cms`, `content` | CMS / Admin | Medium |
+| `api`, `rest`, `graphql`, `endpoint` + no frontend | API-only | Medium |
+| `crawler`, `scraper`, `spider`, `seed`, `crawl` | Crawler / Scraper | Medium |
+| `mobile`, `react-native`, `flutter`, `expo` | Mobile app | Medium |
+| `worker`, `job`, `queue`, `cron`, `background` | Background processing | Medium |
+
+### Phase 3: Skill Selection
+
+After detection, select skills using this algorithm:
+
+```
+Activate always:
+  └── 00-orchestrator   (this skill)
+  └── 01-discovery      (to locate and understand the project)
+  └── 05-documentation  (every agent leaves docs better)
+
+Activate if business logic exists or is being added:
+  └── 03-business-architecture
+
+Activate if architecture decisions are needed:
+  └── 04-architecture
+
+Activate if existing code needs inspection:
+  └── 06-codebase-audit
+
+Activate if project handles:
+  - user data → 07-security
+  - payments → 07-security
+  - authentication → 07-security
+  - external integrations → 07-security
+  - PII → 07-security
+
+Activate if code changes are planned:
+  └── 08-testing
+
+Activate if performance is a concern or changes affect performance:
+  └── 09-performance
+
+Activate if comprehensive review is needed:
+  └── 10-audit   (runs 06 + 07 + 04 + 03 in sequence)
+
+Activate detected stack skill:
+  └── stacks/[detected-language]/
+
+Activate detected framework skill:
+  └── frameworks/[detected-framework]/
+
+Activate detected infrastructure skill:
+  └── stacks/[detected-db]/     (if database-specific guidance needed)
+  └── stacks/[detected-cache]/  (if cache-specific guidance needed)
+  └── stacks/[detected-infra]/  (if infra-specific guidance needed)
+```
+
+### Phase 4: Workflow Selection
+
+Based on the task type, select the appropriate workflow:
+
+| Task | Workflow |
+|---|---|
+| New project from scratch | Greenfield workflow (`workflow.md`) |
+| Add feature to existing project | Improve workflow |
+| Fix bug in existing project | Improve workflow + testing |
+| Audit existing project | Audit workflow (`10-audit`) |
+| Refactor existing code | Reconcile workflow (Partial) |
+| Stabilize broken project | Stabilize workflow (Broken) |
+| Document existing project | Documentation workflow (`05-documentation`) |
+| Security review | Security workflow (`07-security`) |
+
+---
+
+## Decision Trees
+
+### "Should I introduce a new technology?"
+
+```
+Is the current technology insufficient for the task?
+├── NO → Do not introduce new technology
+└── YES
+     │
+     Is the gap measurable (performance, capability, maintainability)?
+     ├── NO → Do not introduce new technology
+     └── YES
+          │
+          Is there an existing technology in the stack that can be extended?
+          ├── YES → Extend it first. Propose the extension in an ADR.
+          └── NO
+               │
+               Does the new technology solve a problem the project actually has?
+               ├── NO → Do not introduce it
+               └── YES
+                    │
+                    Have you documented the decision in an ADR?
+                    ├── NO → Write the ADR first
+                    └── YES → Proceed
+```
+
+### "Should I rewrite this?"
+
+```
+Does the existing code work?
+├── YES → Do not rewrite. Improve incrementally.
+└── NO
+     │
+     Is the problem architectural or implementation?
+     ├── Implementation → Fix the implementation
+     └── Architectural
+          │
+          Can the architecture be adjusted incrementally?
+          ├── YES → Adjust incrementally
+          └── NO
+               │
+               Is a rewrite the only viable path?
+               ├── NO → Find another path
+               └── YES
+                    │
+                    Have you documented the current problems, the proposed architecture,
+                    the migration plan, and the rollback plan in an ADR?
+                    ├── NO → Write the ADR first
+                    └── YES → Proceed with migration plan
+```
+
+### "Is this AI-appropriate?"
+
+```
+Is the task deterministic? (same input → same correct output, always)
+├── YES → Use deterministic tools. Do not use AI.
+│         Examples: data transformation, validation, formatting, testing,
+│                   build steps, migrations, config generation
+└── NO (requires judgment, synthesis, or reasoning)
+     │
+     Does the task benefit from reasoning?
+     ├── NO → Use a simpler heuristic or rule-based approach
+     └── YES → AI may be appropriate
+```
+
+---
+
+## Skill Metadata Schema
+
+Every skill file must begin with this YAML header:
+
+```yaml
+skill:
+  name: skill-name           # kebab-case, matches directory name
+  version: X.Y.Z             # SemVer
+  compatible:
+    project_skills: ">=1.0"  # min version of this repository
+  requires:                  # skills that must be activated first
+    - discovery
+  outputs:                   # artifacts this skill produces
+    - path/to/output.md
+  conflicts:                 # skills that should not be active simultaneously
+    - unrelated-skill
+```
+
+The orchestrator uses `requires` to order activation and `conflicts` to prevent contradictory skill combinations.
+
+---
+
+## What the Orchestrator Produces
+
+After classification and selection, the orchestrator writes:
+
+### `selected-skills.md`
+
+```
+Project: [name]
+State: [greenfield | healthy | partial | broken]
+Detected stack: [language], [framework], [database], [infrastructure]
+Detected domain: [project type]
+Activated skills:
+  - 00-orchestrator
+  - 01-discovery
+  - 05-documentation
+  - 03-business-architecture
+  - stacks/typescript
+  - frameworks/nextjs
+  - stacks/postgresql
+Reason for each activation: [brief justification]
+```
+
+### `project-classification.md`
+
+```
+Project classification
+======================
+State: [state]
+Rationale: [why this state was chosen]
+Risk level: [low | medium | high]
+Maturity: [new | early | maturing | mature]
+Scale: [solo | small team | medium team | large team | unknown]
+```
+
+---
+
+## Anti-Patterns
+
+The orchestrator must prevent these:
+
+1. **Stack forcing** — selecting a skill because "this should be a Rust project" instead of because Cargo.toml says so
+2. **Over-skilling** — activating 20 skills for a simple script
+3. **Under-skilling** — skipping security for a project that handles payments
+4. **Assuming architecture** — assuming microservices, monolith, serverless, etc. without evidence
+5. **Assuming business model** — assuming SaaS, marketplace, etc. without evidence
+6. **Skipping discovery** — jumping to implementation before understanding the project
+7. **Master prompt fallacy** — trying to use all skills at once instead of selecting the minimum set
+AGENTS_EOF

package/skills/00-orchestrator/decision-tree.md

@@ -0,0 +1,93 @@
+# Decision Tree Reference
+
+This file consolidates the decision trees from SKILL.md into a quick-reference format.
+
+## Project State
+
+```
+Existing code?
+├── NO → Greenfield
+└── YES
+     │
+     Is the code working and well-structured?
+     ├── YES → Healthy → Improve
+     ├── SOME (mixed) → Partial → Reconcile
+     └── NO (fundamentally broken) → Broken → Stabilize
+```
+
+## New Technology
+
+```
+Current technology insufficient?
+├── NO → Stop
+└── YES
+     │
+     Gap measurable?
+     ├── NO → Stop
+     └── YES
+          │
+          Existing technology extendable?
+          ├── YES → Extend + ADR
+          └── NO
+               │
+               New technology solves actual problem?
+               ├── NO → Stop
+               └── YES
+                    │
+                    ADR written?
+                    ├── NO → Write ADR
+                    └── YES → Proceed
+```
+
+## Rewrite
+
+```
+Code works?
+├── YES → Do not rewrite
+└── NO
+     │
+     Problem type?
+     ├── Implementation → Fix implementation
+     └── Architectural
+          │
+          Incremental adjustment possible?
+          ├── YES → Adjust incrementally
+          └── NO
+               │
+               Rewrite only viable path?
+               ├── NO → Find another path
+               └── YES
+                    │
+                    ADR with problems + proposal + migration + rollback?
+                    ├── NO → Write ADR
+                    └── YES → Proceed
+```
+
+## AI Appropriateness
+
+```
+Task deterministic?
+├── YES → Deterministic tools only
+└── NO
+     │
+     Benefits from reasoning?
+     ├── NO → Heuristic / rule-based
+     └── YES → AI may be appropriate
+```
+
+## Skill Activation
+
+```
+Always: orchestrator, discovery, documentation
+Business logic? → + business-architecture
+Architecture decisions? → + architecture
+Existing code inspection? → + codebase-audit
+User data / payments / auth / PII? → + security
+Code changes planned? → + testing
+Performance concern? → + performance
+Comprehensive review? → + audit (06+07+04+03)
+───
+Detected language → + stacks/[language]
+Detected framework → + frameworks/[framework]
+Detected infra → + stacks/[infra]
+```

package/skills/00-orchestrator/project-detection.md

@@ -0,0 +1,81 @@
+# Project Detection
+
+## Purpose
+
+Project detection determines what kind of project this is before any work begins. It is the input to skill selection.
+
+## Detection Process
+
+### 1. Locate the project
+
+A repository may contain:
+- A single project at the root
+- A monorepo with multiple projects
+- A partial project (some code, some design)
+- A design-only project (no code yet)
+
+Use `01-discovery/SKILL.md` to locate the actual project.
+
+### 2. Detect the technology
+
+Use the detection tables in `SKILL.md` (Phase 2) to identify:
+- Programming language
+- Framework and version
+- Database and ORM
+- Cache, queue, search
+- Infrastructure and deployment
+- CI/CD
+
+### 3. Detect the project type
+
+Use the project-type signals in `SKILL.md` (Phase 2) to identify:
+- SaaS / commercial
+- Marketplace
+- E-commerce
+- Fintech
+- Directory
+- CMS / admin
+- API-only
+- Crawler / scraper
+- Mobile app
+- Background processing
+- Static site
+- Library / SDK
+- Internal tool
+- Unknown (must not assume)
+
+### 4. Detect the business domain
+
+Read the business signals:
+- What is being sold, provided, or tracked?
+- Who are the actors?
+- What are the transactions?
+- What data is central?
+
+### 5. Detect maturity and risk
+
+| Signal | Maturity | Risk |
+|---|---|---|
+| No code | New | Low (nothing broken yet) |
+| Code, no tests | Early | Medium (regressions possible) |
+| Code, tests, CI | Maturing | Medium |
+| Code, tests, CI, docs, ADR | Mature | Low |
+| Security issues found | Any | High |
+| Data integrity issues | Any | High |
+| No auth on sensitive endpoints | Any | High |
+| Hardcoded secrets | Any | High |
+
+### 6. Detect team and scale
+
+| Signal | Scale |
+|---|---|
+| Single developer, no CI | Solo / small |
+| Team, some process | Small team |
+| Multiple teams, CI/CD, monitoring | Medium team |
+| Explicit scaling infrastructure, on-call | Large team |
+
+If no signals are available, record "unknown" — do not assume.
+
+## Output
+
+The detection produces a structured summary that the orchestrator uses for skill selection. See `SKILL.md` for the output format.

package/skills/00-orchestrator/skill-selection.md

@@ -0,0 +1,87 @@
+# Skill Selection
+
+## Algorithm
+
+```
+1. Run discovery → locate the project
+2. Detect technology → language, framework, database, infrastructure
+3. Detect project type → domain and business model
+4. Classify state → greenfield / healthy / partial / broken
+5. Select core skills → always-on + contextually required
+6. Select stack skills → detected language, framework, infrastructure
+7. Select workflow → based on task type and project state
+8. Write selected-skills.md
+```
+
+## Always-On Skills
+
+These are active for every project, every session:
+
+| Skill | Why |
+|---|---|
+| 00-orchestrator | This skill — the decision engine |
+| 01-discovery | Locate and understand the project |
+| 05-documentation | Every agent leaves docs better |
+
+## Conditional Core Skills
+
+| Condition | Skill |
+|---|---|
+| Business logic exists or is being added | 03-business-architecture |
+| Architecture decisions needed | 04-architecture |
+| Existing code needs inspection | 06-codebase-audit |
+| User data, payments, auth, PII, external integrations | 07-security |
+| Code changes planned | 08-testing |
+| Performance concern or changes affecting performance | 09-performance |
+| Comprehensive review requested | 10-audit |
+
+## Stack Skills
+
+Activated by detection only:
+
+| Detected | Skill |
+|---|---|
+| JavaScript | stacks/javascript |
+| TypeScript | stacks/typescript |
+| Python | stacks/python |
+| PHP | stacks/php |
+| Rust | stacks/rust |
+| Go | stacks/go |
+| Java | stacks/java |
+| Ruby | stacks/ruby |
+| C# / .NET | stacks/dotnet |
+| React | frameworks/react |
+| Next.js | frameworks/nextjs |
+| Laravel | frameworks/laravel |
+| Django | frameworks/django |
+| FastAPI | frameworks/fastapi |
+| Axum | frameworks/axum |
+| Ruby on Rails | frameworks/rails |
+| Spring Boot | frameworks/spring |
+
+## Infrastructure Skills
+
+| Detected | Skill |
+|---|---|
+| PostgreSQL | stacks/postgresql (or database adapter) |
+| Redis | stacks/redis |
+| Docker | stacks/docker |
+| AWS | stacks/aws |
+| Vercel | stacks/vercel |
+
+## Selection Rules
+
+1. **Minimum set.** Activate only what is needed. A 200-line script needs README + discovery, not 15 skills.
+2. **Detection over assumption.** Never select a stack skill without detection evidence.
+3. **Security is conditional but important.** Skip it for a static site. Never skip it for a project handling payments or user data.
+4. **Documentation is mandatory.** Always active. Non-negotiable.
+5. **Testing is conditional on code changes.** No code changes = no testing skill needed. Planning a change = testing skill needed.
+6. **Audit is a composite.** 10-audit activates 06, 07, 04, and 03 in sequence. Do not activate all four individually if 10-audit is selected.
+
+## Anti-Patterns
+
+- Selecting all skills "just in case"
+- Selecting a stack skill before detecting the stack
+- Skipping security for a project that handles user data
+- Skipping documentation "because it's a small change"
+- Activating framework skill when no framework is detected