Adopt the library in a project
Created and maintained with AI agents. Humans own review and publication.
Proposed · human review required · r3
Start with one delivery path
For a new user, follow your first evidence gate, then use the delivery workflow with the playbook for your project. You will produce a plan, a small piece of work, an actual observation and a review. A gate is a checkpoint with required outputs and blocking conditions. An artifact is an output such as a decision document, source change or test report. Evidence records what someone actually inspected or ran against that output. A planned check is not an observation, and a filled template is not approval.
Use the right profile
| File | Purpose | Who reads it |
|---|---|---|
templates/delivery-profile.json |
Example of the strict JSON input: project type, exact target revision, risk, data, workload, hosting, surfaces, effects and objectives | library.delivery plan, library.delivery assess, and library.project init |
project-profile.json |
Your project's populated JSON delivery profile; this is the name generated by init |
The same tools; the filename differs, the schema does not |
templates/project-profile.yaml |
Optional detailed decision brief: owner, budget, service objectives, residency, recovery and exceptions | Humans and agents; the CLI does not read or convert it |
Start from the JSON template for executable planning. Replace its synthetic
requirements with actual project decisions. For an existing project, keep the
profile and evidence in that project's approved location and run the library CLI
with explicit paths. Do not run init over an existing project: it only creates a
new destination. For a new portable packet, init copies the required tools,
guides, licenses and selected reference examples; those are not your finished product.
For reading and decision support alone, link the relevant guides and copy only
the templates you need; neither packet generation nor MCP is required.
If you also maintain the YAML brief, transfer decisions deliberately:
| Decision brief | Delivery profile | What needs interpretation |
|---|---|---|
name, outcome, non_goals |
project_id, description, objectives, constraints |
Choose a valid stable ID and observable outcomes; do not just rename keys |
data.classification |
data_sensitivity |
Select the supported category after reviewing the actual data |
Measured workload fields |
workload |
Choose a justified category; use unmeasured when measurements are missing |
library_revision |
No corresponding profile field | Pin the library separately; JSON revision means the target project's Git commit |
| Owner, budget, service objectives, residency, recovery, exceptions | Keep in the brief and relevant gate artifacts | These obligations still matter; the planner does not evaluate those YAML fields |
Project type, hosting, surfaces, effects and risk also need explicit decisions in
JSON. There is no automatic conversion or synchronization. When shared assumptions
change, update both documents, regenerate the plan and reassess affected evidence.
Do not add YAML-only fields to the strict JSON schema. Pin the library to a reviewed
release or full commit and use stable guide IDs. Following mutable main silently
can change project policy without project approval.
Create a context diagram and an ADR for the first consequential decision. Record accepted guidance, deliberately deferred controls, an owner, expiry and compensating checks. Keep project-specific agent instructions in AGENTS.md; link supporting material. This library is an agent-maintained proposal source. Its recommendations become project policy only through the project's human decision process.
Three starting examples
- Personal public website: use a static build, content history and a reproducible deployment. Keep private notes, credentials and personal source data out of public Git history and public build assets, including search indexes. A login screen cannot protect publicly downloadable files. A private knowledge base needs private storage and server-enforced access checks for documents, assets, downloads and search; a private repository alone does not make its published output private.
- Small SaaS: begin with a modular application, transactional database and worker only where needed. Define tenant boundaries, payment reconciliation and an operating owner. Before accepting real customers, prove denial across tenants, compatibility during deployment and restoration into an isolated environment.
- High-traffic platform: first measure traffic mix, skew, data growth and dependency limits. Partition or isolate a workload only after demonstrating the constraint and assigning ownership for consistency, migration, on-call response and recovery. A large account count alone does not establish a capacity requirement.
These are original starting recommendations, not universal prescriptions or benchmarked deployment templates.
Turn guidance into acceptance evidence
For each adopted guide, identify the observable obligation and the check that could refute compliance. For example, “tenant isolation” becomes a test where tenant A's authenticated session requests tenant B's object through the API, export and worker paths, and none returns B's data. Record test setup, expected result, executed revision and retained evidence in the testing strategy.
Use the reference profiles to identify missing boundaries. An unexecuted acceptance statement is a planned test, not proof. Do not claim safety because a template is filled in or a generated summary says “passed.” Review the actual result, including failures and omissions.
Revisit without losing control
Consult applicable guides during planning and link them in the implementation task. At review, compare the diff with the chosen decision and failure cases. Before release, validate migration and recovery; during operation, feed measurements and incidents back into ADRs. Upgrade the pinned library through a PR explaining changed obligations, affected projects and the migration or exception plan.
If a new recommendation cannot be validated within the project's budget or ownership capacity, record that gap and simplify the design. Do not silently accept a policy that nobody can operate.
Related decisions
Decision principles · The complete project lifecycle · Testing strategy · Human direction, agent execution · Governance and unanswered decisions
Primary evidence
plugins · github-rulesets · observability · owasp-authorization