@botdigit/agent-blueprint 1.0.0

package/skills/00-orchestrator/workflow.md

@@ -0,0 +1,25 @@
+# Greenfield Workflow
+
+## When to use
+
+No existing code. Starting a project from scratch.
+
+## Sequence
+
+1. **Discover** — understand the domain, the actors, the business
+2. **Architect** — choose architecture deliberately (not by default)
+3. **Document foundations** — write PROJECT.md, ARCHITECTURE.md, the docs you will need
+4. **Plan first increment** — what is the smallest useful version?
+5. **Implement** — follow the architecture
+6. **Test** — verify each increment
+7. **Document** — update docs with what you built
+
+## Rules
+
+- Choose the simplest architecture that can work.
+- Do not choose microservices by default.
+- Do not choose a database by trend. Choose by fit.
+- Do not add a framework you do not need.
+- Every architectural decision gets an ADR.
+- Set up documentation structure before writing code.
+- Write tests alongside code, not after.

package/skills/01-discovery/SKILL.md

@@ -0,0 +1,66 @@
+# 01-Discovery Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** (none — this is the first skill)
+**Outputs:** project-location.md, repository-map.md
+
+---
+
+## Purpose
+
+Find the project within the repository. A repository may contain a single project at root, a monorepo, a partial project, or no code at all. Discovery locates what actually exists before anything else happens.
+
+---
+
+## Process
+
+### Step 1: Map the repository
+
+List the top-level structure. Look for:
+
+- Single project at root (most common)
+- `apps/`, `services/`, `packages/`, `modules/` → monorepo
+- `src/`, `app/`, `backend/`, `frontend/`, `api/` → separated concerns
+- `docs/` only → documentation project, no code yet
+- Nothing recognizable → may be a design or planning repo
+
+### Step 2: Identify project boundaries
+
+For monorepos, identify which sub-projects exist and which one the current task relates to.
+
+For separated structures, identify frontend vs backend vs shared.
+
+### Step 3: Record what is found
+
+For each project or sub-project, record:
+
+- Path
+- What it appears to be (frontend, backend, worker, library, etc.)
+- Any detection signals present (package.json, Cargo.toml, etc.)
+- Whether code exists or only design/docs
+
+### Step 4: Identify the target
+
+Determine which project the current task applies to. If ambiguous, report the ambiguity rather than guessing.
+
+---
+
+## Outputs
+
+### project-location.md
+
+```
+Discovery Results
+=================
+Repository: [url or path]
+Structure: [single | monorepo | separated | design-only | unknown]
+Projects found:
+  - [path]: [type], [code: yes/no], [signals: ...]
+Target project: [path or "not yet determined"]
+Rationale: [why this target]
+```
+
+### repository-map.md
+
+A tree or list of the repository structure with annotations about what each directory appears to contain.

package/skills/02-project-context/SKILL.md

@@ -0,0 +1,89 @@
+# 02-Project-Context Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery
+**Outputs:** project-context.md
+
+---
+
+## Purpose
+
+Build a structured understanding of the project's technology context: languages, frameworks, databases, infrastructure, and tooling. This is the input to stack skill selection.
+
+---
+
+## Process
+
+### 1. Detect programming language(s)
+
+Inspect the signals listed in `00-orchestrator/SKILL.md` (Phase 2, Programming Language table). Record version if detectable:
+- `package.json` → engine/node versions
+- `Cargo.toml` → rust version in `[package]` orrust-toolchain file
+- `go.mod` → go version directive
+- `pom.xml` / `build.gradle` → java version
+- `Gemfile` → ruby version
+- `*.csproj` → target framework
+- `pyproject.toml` / `requirements.txt` → python version
+
+### 2. Detect framework(s) and version
+
+Inspect signals from the Framework table. Record major version if detectable.
+
+### 3. Detect database and data stores
+
+- Primary database (from config, env, connection strings, migrations)
+- Secondary stores (cache, queue, search, blob storage)
+- ORM or query builder in use
+- Migration system
+
+### 4. Detect infrastructure and deployment
+
+- Containerization (Docker, none)
+- Orchestration (Kubernetes, none, platform-managed)
+- Hosting platform (Vercel, Netlify, AWS, GCP, Azure, bare metal, unknown)
+- CI/CD system and outline
+- Environment configuration pattern (.env, config files, secrets manager)
+
+### 5. Detect third-party services
+
+- Auth provider
+- Payment provider
+- Email / notification
+- Storage (S3, Cloudflare R2, etc.)
+- Monitoring / observability
+- CDN
+- Any API integrations mentioned in code or docs
+
+### 6. Record what is NOT detectable
+
+If something cannot be detected from available signals, record "not detectable from current evidence" rather than guessing.
+
+---
+
+## Output
+
+### project-context.md
+
+```
+Project Context
+===============
+Language: [language] [version if known]
+Framework: [framework] [version if known]
+Frontend: [framework or "none"]
+Backend: [framework or "none"]
+Database: [database] [version if known]
+ORM: [orm or "none"]
+Cache: [redis/none/unknown]
+Queue: [system or "none"]
+Search: [engine or "none"]
+Storage: [system or "none"]
+Infrastructure: [docker/k8s/platform/unknown]
+Deployment: [platform or "unknown"]
+CI/CD: [system or "none"]
+Environment: [dotenv/config/secrets-manager/unknown]
+Third-party services:
+  - [service]: [purpose]
+  - ...
+Not detectable: [list of things that could not be determined]
+```

package/skills/03-business-architecture/SKILL.md

@@ -0,0 +1,231 @@
+# 03-Business-Architecture Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context
+**Outputs:** business-model.md, actors.md, business-rules.md, workflows.md, state-machines.md (as applicable)
+
+---
+
+## Purpose
+
+Understand the business before touching code. This skill directs the agent to discover and document what the project does, who it is for, what rules govern it, and how it works — as a business system, not as code.
+
+Business logic comes before code structure.
+
+---
+
+## Process
+
+### 1. Identify the actors
+
+Who interacts with this system?
+
+- End users (what kind?)
+- Administrators
+- Customers
+- Sellers / providers
+- Visitors (unauthenticated)
+- System actors (cron, webhooks, integrations)
+- Third-party systems
+
+For each actor, record:
+- Who they are
+- What they can do
+- What they can see
+- What they cannot do
+
+### 2. Identify the business model
+
+How does this project create or capture value?
+
+- What is being sold, provided, or tracked?
+- Is it a product, service, marketplace, platform, tool?
+- What is the unit of transaction?
+- Is there pricing? How does it work?
+- Is there revenue? From what?
+- Is there a free tier, trial, or alternative access model?
+
+If pricing exists, find the single source of truth for it. If pricing is scattered across code, flags, spreadsheets, and hardcoded values — record that as a finding, not a normal state.
+
+### 3. Identify business entities
+
+What are the core things the business tracks?
+
+Examples: User, Account, Product, Listing, Order, Payment, Subscription, Scan, Report, Document, Invoice, Credential.
+
+For each entity, record:
+- What it represents
+- What data it holds
+- Who owns it
+- What creates it
+- What modifies it
+- What deletes it (if anything)
+- What its lifecycle is
+
+### 4. Identify business processes
+
+What does the business actually do, step by step?
+
+For each process:
+- Who initiates it
+- What happens at each step
+- What data changes
+- What can go wrong
+- What happens when it fails
+- Who is notified
+- What the end state is
+
+### 5. Identify business rules
+
+What are the constraints the business operates under?
+
+Record rules in this form:
+
+```
+RULE: [description]
+IF [condition]
+THEN [outcome]
+EXCEPT [exceptions]
+NEVER [what must not happen]
+```
+
+Examples of rule categories:
+- Authorization (who can do what)
+- Validation (what data is acceptable)
+- State transitions (what can change to what)
+- Pricing rules (how prices are calculated)
+- Access rules (who can see what)
+- Compliance rules (what must be preserved, retained, or restricted)
+- Integrity rules (what must never be inconsistent)
+
+### 6. Identify state machines
+
+What entities have a lifecycle with distinct states?
+
+For each state machine:
+- What entity
+- What states
+- What transitions are allowed
+- What triggers each transition
+- What is validated before each transition
+- What happens after each transition
+- What states are terminal
+
+### 7. Identify edge cases and exceptional flows
+
+What happens when:
+- A payment fails?
+- A user is banned?
+- Data is missing?
+- A third-party service is down?
+- A race condition occurs?
+- A user tries to do something they should not?
+- The same action is performed twice?
+
+### 8. Identify domain boundaries
+
+Where does one domain end and another begin?
+
+- What data belongs to what subsystem?
+- What cross-domain interactions exist?
+- What integrations cross boundaries?
+- What should NOT cross boundaries?
+
+---
+
+## Reasoning Questions
+
+The agent must be able to answer these before implementing business logic changes:
+
+- WHO performs this action?
+- WHAT does the action do?
+- WHY does it exist?
+- WHEN does it run?
+- UNDER WHAT CONDITIONS?
+- WHAT CAN CHANGE?
+- WHAT MUST NEVER CHANGE?
+- WHO OWNS THE DATA?
+- WHO CAN PERFORM THE ACTION?
+- WHAT HAPPENS WHEN IT FAILS?
+- WHAT IS THE WORST CASE?
+- WHAT IS THE COST OF BEING WRONG?
+
+---
+
+## Output
+
+### business-model.md
+
+```
+Business Model
+==============
+What this project does: [description]
+Value proposition: [what value is created]
+Revenue model: [how money flows, or "not applicable"]
+Pricing: [how pricing works, or "not applicable"]
+Single source of truth for pricing: [location or "MISSING"]
+Core entities: [list]
+Actors: [list with brief description]
+```
+
+### actors.md
+
+```
+Actors
+======
+[For each actor:]
+- Name: [actor name]
+- Type: [user | admin | system | third-party | ...]
+- Can do: [actions]
+- Can see: [data]
+- Cannot do: [restricted actions]
+- Authentication: [how this actor is authenticated]
+```
+
+### business-rules.md
+
+```
+Business Rules
+==============
+[For each rule:]
+ID: [BR-001]
+Category: [authorization | validation | pricing | state | access | compliance | integrity]
+Rule: [description]
+Condition: [when it applies]
+Outcome: [what happens]
+Exception: [exceptions]
+Invariant: [what must never happen]
+Source: [where this rule is implemented or documented]
+```
+
+### workflows.md
+
+```
+Workflows
+=========
+[For each workflow:]
+Name: [workflow name]
+Actor: [who initiates]
+Steps:
+  1. [step description]
+     - Data changes: [what changes]
+     - Failures: [what happens on failure]
+  2. ...
+End state: [final state]
+Error handling: [how errors are handled]
+```
+
+### state-machines.md
+
+```
+State Machines
+==============
+[For each state machine:]
+Entity: [entity name]
+States: [list]
+Transitions:
+  [state A] → [state B]: [trigger], [validation], [side effects]
+  ...
+Terminal states: [list]
+```

package/skills/04-architecture/SKILL.md

@@ -0,0 +1,131 @@
+# 04-Architecture Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery, project-context, business-architecture
+**Outputs:** architecture.md, architecture-gaps.md, decisions/ADR-XXX.md
+
+---
+
+## Purpose
+
+Understand, review, and document the project's architecture. This skill directs the agent to assess the existing architecture (if any), identify gaps, and make or record architectural decisions with reasoning.
+
+Every architectural decision needs a reason.
+
+---
+
+## Process
+
+### 1. Map the current architecture
+
+Identify:
+- High-level components and their responsibilities
+- How components communicate (HTTP, queues, shared DB, events, in-process)
+- Data flow between components
+- Boundaries between subsystems
+- Deployment topology (processes, services, instances)
+- External dependencies
+
+### 2. Assess architectural style
+
+Determine what style the project uses or should use:
+
+- Modular monolith
+- Microservices
+- Serverless functions
+- Single process
+- Client-server
+- Event-driven
+- Layered
+- Hexagonal / ports and adapters
+- Other
+
+Record why this style was chosen (or note "not documented" if unknown).
+
+### 3. Evaluate against principles
+
+For each component and interaction, ask:
+- Is this the simplest thing that can work?
+- Is this component's responsibility clear and focused?
+- Are boundaries well-defined?
+- Is the data flow understandable?
+- Are dependencies justified?
+- Is this architecture appropriate for the project's scale and team?
+- Does it match the business domain?
+
+### 4. Identify gaps
+
+Record gaps in these categories:
+- Missing documentation
+- Unclear boundaries
+- Hidden coupling
+- Missing error handling strategy
+- Missing observability
+- Missing security boundaries
+- Scaling bottlenecks
+- Technology choices that no longer fit
+- Missing backward compatibility strategy
+- Missing migration strategy for data or schema
+
+### 5. Make or record decisions
+
+Every architectural decision that is not already documented must be recorded as an ADR. See `templates/adr/`.
+
+An ADR must contain:
+- Title
+- Status (proposed, accepted, deprecated, superseded)
+- Context: what problem this decision addresses
+- Decision: what was decided
+- Consequences: what this decision implies (positive and negative)
+- Alternatives considered: what else was considered and why it was not chosen
+
+---
+
+## Architecture Assessment Questions
+
+- What is the simplest architecture that satisfies the business requirements?
+- Are we over-engineering? Under-engineering?
+- Does the architecture match the team's ability to maintain it?
+- Can we deploy independently where it matters?
+- Are there single points of failure?
+- Is data integrity protected across component boundaries?
+- Can we reason about the system? If not, why?
+- Are there components that do too much? Too little?
+- Are there circular dependencies?
+- Is the dependency direction correct (dependencies point toward stability)?
+
+---
+
+## Output
+
+### architecture.md
+
+```
+Architecture
+============
+Style: [architectural style]
+Rationale: [why this style, or "not documented"]
+Components:
+  - [name]: [responsibility], [communicates with: ...]
+Data flow: [description or diagram]
+Deployment: [how it runs]
+External dependencies: [list]
+Boundaries:
+  - [boundary description]
+```
+
+### architecture-gaps.md
+
+```
+Architecture Gaps
+=================
+[Gap ID]: [description]
+Severity: [low | medium | high | critical]
+Impact: [what this gap causes]
+Recommendation: [what to do]
+```
+
+### decisions/
+
+Each ADR as a separate file. Use `templates/adr/` as the template.

package/skills/05-documentation/SKILL.md

@@ -0,0 +1,133 @@
+# 05-Documentation Skill
+
+**Version:** 1.0.0
+**Compatible:** project_skills >= 1.0
+**Requires:** discovery
+**Outputs:** documentation-map.md, and any documents from templates/ as appropriate
+
+---
+
+## Purpose
+
+Establish and maintain living documentation for the project. Every agent must leave the project better documented than it found it.
+
+Documentation is not a one-time task. It is a continuous obligation.
+
+---
+
+## Principle: Minimum Sufficient Documentation
+
+Do not create every document. Create the minimum set that allows a person (or agent) to understand, operate, maintain, and safely change the project.
+
+### Documentation Tiers
+
+| Tier | Project Type | Documents |
+|---|---|---|
+| 1 — Minimal | Script, small tool, simple service | README.md |
+| 2 — Standard | Small web app, API, internal tool | README + PROJECT + ARCHITECTURE + DATABASE + API + SECURITY |
+| 3 — Full | SaaS, marketplace, commercial product | Tier 2 + BUSINESS + BUSINESS-MODEL + ACTORS + TESTING + DEPLOYMENT + OPERATIONS |
+| 4 — Regulated | System with compliance, audit, or data governance requirements | Tier 3 + COMPLIANCE + AUDIT + DATA-GOVERNANCE + DISASTER-RECOVERY |
+
+The orchestrator selects the tier. Within a tier, use judgment — a simple SaaS may not need all of Tier 3 immediately.
+
+---
+
+## Documentation Standard
+
+Every project using Agent Blueprint should follow this documentation structure:
+
+```
+docs/
+├── 00-project/
+│   ├── overview.md       # What this project is
+│   ├── goals.md          # Why it exists, what it aims to achieve
+│   ├── scope.md          # What is in scope and out of scope
+│   └── glossary.md       # Domain terms
+│
+├── 01-business/
+│   ├── business-model.md
+│   ├── actors.md
+│   ├── processes.md
+│   ├── business-rules.md
+│   └── state-machines.md
+│
+├── 02-architecture/
+│   ├── architecture.md
+│   ├── domains.md
+│   ├── data-flow.md
+│   ├── integrations.md
+│   └── decisions/        # ADRs
+│
+├── 03-engineering/
+│   ├── code-structure.md
+│   ├── database.md
+│   ├── api.md
+│   └── frontend.md
+│
+├── 04-security/
+│   └── security.md
+│
+├── 05-testing/
+│   └── testing.md
+│
+├── 06-performance/
+│   └── performance.md
+│
+├── 07-deployment/
+│   └── deployment.md
+│
+├── 08-operations/
+│   └── operations.md
+│
+├── 09-audits/
+│   └── [audit reports]
+│
+└── 10-roadmap/
+    └── roadmap.md
+```
+
+Not every project needs every directory. Create only what applies.
+
+---
+
+## Documentation Rules
+
+1. Documentation lives in `docs/` or at the project root for top-level files (README, PROJECT.md, etc.).
+2. Every document has a last-reviewed date and reviewer.
+3. Every document that describes behavior must be updateable by the agent that changes the behavior.
+4. If code and documentation disagree, the agent must resolve the disagreement — not assume the documentation is wrong.
+5. Outdated documentation is worse than no documentation. When in doubt, update or remove.
+6. Do not duplicate information across documents. Reference instead.
+
+---
+
+## What Every Agent Must Update
+
+After making changes, the agent must verify:
+
+- [ ] README.md reflects the current state
+- [ ] Any architecture change is reflected in architecture docs
+- [ ] Any business logic change is reflected in business docs
+- [ ] Any new API is documented
+- [ ] Any new database schema is documented
+- [ ] Security-relevant changes are flagged
+- [ ] Changelog is updated
+- [ ] New dependencies are justified
+
+---
+
+## Output
+
+### documentation-map.md
+
+```
+Documentation Map
+=================
+Tier: [1 | 2 | 3 | 4]
+Documents:
+  - [path]: [status: present | missing | outdated], [last reviewed]
+Gaps:
+  - [document that should exist but does not]
+Outdated:
+  - [document that exists but is outdated]
+```