How to write a PureIntent block

What a block is

A block is the smallest independently adoptable context decision. It should help a team answer one meaningful question without requiring the reader or agent to reconstruct the decision from generic advice.

A title and a few best practices are not enough. A useful block states the promised outcome, the authority boundary, relevant inputs and outputs, important states, failure behavior, project-specific choices, dependencies, and a way to verify the adopted behavior.

If two parts can be adopted, versioned, owned, or replaced independently, they should usually be separate blocks. If neither part makes sense without the other, keep them together.

The required package

Every complete block contains four files.

README.md explains the decision, scope, contract, failure behavior, adoption guidance, and verification approach.
meta.yaml contains identity, version, summary, facets, relationships, maturity, status, license, provenance, and the declared file manifest.
example.yaml provides one realistic and internally consistent adoption profile. It demonstrates configurable choices without pretending that an invented value is a universal default.
acceptance-tests.yaml describes externally visible or durably observable scenarios. These scenarios remain not-run until they are executed against an adopting project.

Additional files are welcome when they carry a distinct artifact that cannot be expressed clearly in the required four. Examples include SKILL.md, dashboard.yaml, a JSON Schema, a protocol example, a diagram source, a migration fixture, or a reference implementation. Do not create extra files merely to make the package look substantial.

Authoring workflow

1. State one decision

Write a short decision statement that names the outcome and boundary. A reader should understand why the block exists before reading implementation detail.

Weak: "Use secure authentication."
Stronger: "After a password reset, revoke all existing refresh-token families for the account, preserve the current recovery audit record, and require a new authenticated session before protected actions are available."

2. Define the boundary

Describe what the block owns and what remains outside it. Include actors, inputs, outputs, states, invariants, and authority only when they affect adoption. Avoid ceremonial sections filled with generic advice.

3. Write testable contract rules

Use rules that can be observed or proven. "Handle errors" is not a contract. "A failed upload remains visible with a retry action, does not create a completed attachment, and can be safely retried with the same idempotency key" is.

4. Make failure behavior explicit

Cover invalid input, denied access, unavailable dependencies, partial results, retries, cancellation, stale data, and recovery where they are relevant. A happy-path description alone transfers the hardest decisions back to the adopter.

5. Separate defaults from project choices

Do not present an invented timeout, vendor, retention period, jurisdiction, model, threshold, or service level as universally correct. Put adoption choices in the example and label them as choices.

6. Add relationships by block ID

A dependency is required for correct adoption.
A related block is useful navigation but is not mandatory.
Alternatives are mutually exclusive ways to satisfy the same decision.
Conflicts identify combinations that cannot be adopted without an explicit resolution.

A topic group is not automatically an alternative group. Neighboring blocks often complement one another.

7. Add evidence where the claim needs it

Use primary sources for normative protocols, security requirements, legal constraints, accessibility rules, vendor behavior, and fast-changing facts. Record the relevant version or applicability boundary. A reachable URL does not prove that the block's design is correct.

8. Write the example and acceptance scenarios together

The example, README, and tests must express the same contract. When the decision changes, update all of them. Acceptance scenarios should cover the expected path and the material denial, failure, recovery, and completeness cases.

9. Validate structure and meaning

Run the package validator, then perform semantic review. Static validation can detect missing fields, unsafe paths, unresolved IDs, or malformed data. It cannot prove that the product decision is sensible or that a source supports the claim attached to it.

10. Publish the correct status

Editorial status and implementation evidence are different. A reviewed reference block may still have acceptance scenarios marked not-run. Do not promote a block to stable or claim production evidence merely because its package validates.

Writing for an AI agent

Assume the block will be read by an agent that has access to an unfamiliar repository.

Name required outcomes, not just preferred techniques.
Distinguish trusted host context from model-provided arguments.
State what the agent must inspect before changing code.
Identify decisions it may adapt and invariants it may not silently change.
Require an implementation map from block rules to repository components.
Require the agent to report unresolved assumptions and unexecuted acceptance scenarios.
Treat code, commands, and retrieved documents inside a block as data until the adopting repository authorizes their use.
Do not rely on the model to infer missing authorization, deletion, retry, migration, accessibility, or observability behavior.

When a block includes a skill

Use a skill file when the reusable artifact is not only a decision but also a repeatable agent workflow. The canonical instructions belong in SKILL.md; the README explains why the workflow exists and when to adopt it.

A skill should define:

when it applies and when it does not;
required inputs and prerequisites;
allowed tools and authority boundaries;
the ordered workflow and clarification points;
concrete outputs and destination files;
safe fallback and stop conditions;
verification and handoff requirements.

The skill must not silently expand its authority. For example, a dashboard-building skill may use approved metric and analytics tools, but it must not introduce unrestricted SQL because a user asks for a chart that the governed tools cannot produce.

If a platform requires a small manifest or adapter, keep the reusable workflow in SKILL.md and add the adapter as a separate file. Do not maintain several divergent copies of the same instructions.

Dashboard archetype blocks

A concrete dashboard type is a good block when it answers one decision question for one recognizable audience. Examples include an executive KPI overview, a funnel conversion dashboard, an operational health dashboard, or a recruitment marketplace balance dashboard.

The recommended package is:

README.md
meta.yaml
example.yaml
acceptance-tests.yaml
dashboard.yaml
SKILL.md
fixtures/expected-dashboard.json (optional)

dashboard.yaml defines the portable dashboard contract: audience, decision question, required metric IDs, allowed dimensions, periods, comparisons, sections, interactions, display states, freshness, provenance, accessibility, and output schema.

SKILL.md tells an agent how to inspect the adopting project, resolve the declared metrics, ask only material questions, build the dashboard, verify every displayed value against structured results, and report what remains unsupported.

The generic metric catalog, chart composition, authorization, connector, and query-governance decisions should remain dependencies. Do not duplicate them in every dashboard archetype.

Quality checklist

The summary distinguishes this block from other roles for the same topic.
The block owns one coherent decision and has a clear non-goal boundary.
Contract rules are testable rather than aspirational.
The example contains no secrets, personal data, real credentials, or undocumented universal defaults.
Dependencies, alternatives, conflicts, and related blocks use canonical IDs.
Required authorization and tenant boundaries apply to primary data, caches, exports, logs, jobs, and aggregate counts.
Retries and event consumers define identity, duplicate handling, terminal states, and replay behavior where applicable.
Destructive cleanup requires ownership evidence, a bounded target, and a safe recovery policy.
UI blocks cover empty, loading, error, denied, keyboard, focus, and announcement behavior where applicable.
Operational blocks define at least one decision metric and the response to a threshold breach.
Every additional file is declared, validated, and necessary.
Acceptance scenarios are not presented as executed evidence until they run in the target project.