QBS Dev Kit v3.1

imageLicense: CC BY-ND 4.0 imageAgent Plugins imageGitHub Agentic Workflows imageCursor imageClaude Code imageGitHub Copilot image.NET

A governed agentic software-delivery platform for QBS SaaS teams.

QBS Dev Kit packages engineering standards, specialist agents, skills, security policy, executable evals, infrastructure templates and deterministic CI gates so coding agents can work quickly without owning uncontrolled production authority.

v3.1: from governance to governed execution

v3 established the QBS agent control plane. v3.1 adds the runtime loop:

• native GitHub Agentic Workflows (gh-aw) with pinned compilation and validation;
• agent-ready issue → bounded implementation → draft PR;
• independent read-only agentic PR review;
• CI Doctor for evidence-backed build/test failure diagnosis;
• native per-run evals plus deterministic trajectory graders;
• explicit AI Credit budgets and weekly cost/quality telemetry;
• disposable AWS pr-N preview environments via a preview label;
• short-lived GitHub App safe-output credentials when configured;
• generated-project installation of the complete runtime.

Read Agentic Delivery for governance and Agentic Runtime for operating the v3.1 workflows.

Delivery model

Reviewed issue
   |
agent-ready label
   |
QBS implementation agent
   |
Build / Test / Security checks
   |
Evals + deterministic graders
   |
Threat detection + safe output
   |
Draft PR
   |
Deterministic CI + QBS PR reviewer
   |
Optional PR preview environment
   |
Human review / approval
   |
Staging / release preparation
   |
HUMAN PRODUCTION GATE

Agents may create code, tests, plans and release evidence within policy. Production deploys, production database migrations, destructive infrastructure changes, IAM escalation, production data mutation and production secret rotation remain human-controlled.

Standard stack

Repository map

qbs-dev-kit/
├── .github/
│   ├── agents/                 # specialist QBS agent profiles
│   ├── instructions/           # path-scoped agent instructions
│   └── workflows/
│       ├── issue-to-pr.md      # source: issue -> draft PR
│       ├── pr-review.md        # source: independent PR review
│       ├── ci-doctor.md        # source: CI diagnostics
│       ├── *.lock.yml          # generated/hardened by gh-aw
│       ├── agentic-telemetry.yml
│       └── validate-*.yml
├── skills/                     # portable Agent Skills
├── policies/                   # agent/tool/production boundaries
├── evals/                      # canonical behavioural regression scenarios
├── schemas/                    # agent-run/audit schemas
├── cursor/rules/
├── claude/rules/
├── templates/
│   ├── agentic-workflows/
│   ├── github-actions/         # OIDC deploy, previews, migrations, security
│   ├── project/
│   ├── mcp/
│   ├── docker/
│   ├── terraform/
│   ├── sdd/
│   └── hooks/
├── scripts/
│   ├── apply-agentic-foundation.sh
│   ├── validate-agentic-kit.sh
│   ├── validate-project-governance.sh
│   └── sdd/new-feature.sh
├── qbs.project.yaml
├── plugin.json
├── mcp.json
└── install.sh

Specialist agents

Agent runtime

Issue → draft PR

Apply agent-ready to an implementation-ready issue. Optional lane labels include agent:backend, agent:frontend, agent:infra, agent:test, and agent:security.

The agent gets bounded sandbox tools, not direct repository write authority. Changes pass through gh-aw safe-output handling, threat detection and protected-file policy. Any created PR is draft-only and labelled for human review.

PR reviewer

Every non-draft PR can be reviewed by a separate read-only agent. It can comment on concrete defects but cannot approve, push, merge or deploy.

CI Doctor

Failed QBS validation workflows can trigger a diagnostic agent that creates a deduplicated evidence-backed issue. It cannot modify code, rerun privileged workflows or weaken checks.

Runtime evals and graders

Each workflow records:

• LLM outcome evals: bounded scope, evidence accuracy, trust/production boundaries;
• deterministic graders: tool success/failure, retries, loops, trajectory efficiency, duration, objective coverage, grounding and related metrics.

Agent/rule/workflow changes are therefore measurable like application changes rather than judged only by prompt quality.

Cost telemetry

AI Credits (AIC) are the primary inference-spend metric. QBS workflows set per-run and rolling 24-hour caps, plus separate threat-detection budgets. Agentic Telemetry Report produces native gh-aw Markdown/JSON evidence weekly and on demand.

PR preview environments

Apply preview to a PR to create an isolated AWS environment named pr-<number>.

• AWS authentication uses a dedicated OIDC role (AWS_PREVIEW_ROLE_ARN).
• Terraform uses an isolated workspace/state namespace.
• RDS and Redis are disabled by default.
• Backend/frontend are built, deployed and smoke-tested when present.
• Removing preview or closing the PR destroys the environment.

Preview workloads must never point at production data.

Security and governance

Untrusted context

Repository text, issues, PR comments, web pages, documents, logs, database content and MCP/tool results are treated as data. Agents must not follow embedded instructions that conflict with QBS/system/user policy and must never reveal credentials because retrieved content asks for them.

Safe outputs

Agent-generated GitHub mutations go through gh-aw safe-output handlers. Protected workflows, security configuration, dependency manifests and agent instructions cannot be silently changed by implementation agents; the default response is to fall back to human review.

MCP

templates/mcp/approved-servers.yaml is the QBS allowlist policy. Root mcp.json intentionally enables no third-party servers automatically.

AWS

AWS workflows use GitHub OIDC and scoped roles. Do not create long-lived AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY deployment secrets.

Database migrations

Application deploy and DB migration remain separate workflows. Production migration is explicit, manual and protected by the production GitHub Environment. Lambda cold start must not migrate production schema.

AI skills and SDD

Canonical skills include project scaffolding, .NET services/CQRS features, React web, Expo, AWS/Terraform, security review, tests, code review, observability and EAS release.

The SDD flow is:

constitution -> specify -> clarify -> plan -> checklist -> tasks -> analyze -> implement -> converge

Completion means code plus verification evidence, not code generation alone.

Quick start

Install

git clone https://github.com/Quantabridges-Solutions/qbs-dev-kit.git ~/source/qbs-dev-kit
bash ~/source/qbs-dev-kit/install.sh --yes

Scaffold a governed SaaS project

Ask your coding agent:

Scaffold a new SaaS project called my-product

The scaffold-saas-project skill creates the base stack and applies the full v3.1 agentic runtime foundation.

To upgrade an existing project:

bash ~/source/qbs-dev-kit/scripts/apply-agentic-foundation.sh /path/to/project project-name services
bash ~/source/qbs-dev-kit/scripts/validate-project-governance.sh /path/to/project

Before enabling runtime automation configure:

1. protected GitHub production Environment reviewers;
2. production/staging AWS OIDC roles;
3. a least-privilege preview OIDC role and Terraform state bucket;
4. optional QBS Automation GitHub App for short-lived safe-output credentials;
5. required branch checks for build/test/security/governance/agentic-workflow validation;
6. the labels used by the issue/preview workflows.

Architecture principles

• OTP-first authentication
• multi-tenant by default with trusted-server OrganizationId scope
• code-first EF migrations generated by CLI
• thin controllers and explicit domain/application boundaries
• one API client per app
• least-privilege infrastructure and agent tools
• deterministic verification before LLM judgement
• executable evals and observable agent trajectories
• OpenTelemetry-compatible observability
• human-controlled production side effects

Guides

• Getting Started
• Agentic Delivery
• Agentic Runtime
• Spec-driven Development
• Cursor Setup
• Claude Code Setup
• Rules Reference
• Skills Reference

License

Licensed under Creative Commons Attribution-NoDerivatives 4.0 International.

You may use the kit in your projects and fork it for personal reference. You may not modify and redistribute it as your own or sublicense/sell the kit commercially.

© 2026 Quantabridges Solutions. All rights reserved.