From search to a Solution

Four terms to keep separate

Block

A reusable decision package. A block can be adopted independently and has its own ID and version.

Set

A reusable recipe for a common outcome. A set references required, optional, and alternative blocks, explains why they belong together, and provides an assembly sequence. It does not copy block payloads.

Workspace

The staging collection in the browser (and, when you are signed in, synced to your account). You pin block versions, add project files, and prepare an export. The Workspace is not yet proof that anything has been implemented.

Solution

The exported, version-pinned package you download from the Workspace. PureIntent defines context and verification; it does not treat an exported archive as proof that the program has been implemented.

Implementation

The code, configuration, migrations, tests, and operational changes created in the target repository from a Solution.

How to search

Start with the outcome

Search for the problem or capability in ordinary language: "private RAG assistant with citations," "subscription billing," "recruitment funnel dashboard," or "safe file upload." Technology names are useful constraints, but they should not replace the intended outcome.

Prefer a set when the goal is common

A curated set gives you a reviewed starting sequence and reduces the chance of omitting a supporting decision. Open the set, inspect its outcome and exclusions, then replace or remove blocks only with an explicit reason.

Use blocks to customize

Search individual blocks when no set matches, when an existing set needs one additional capability, or when the project requires a different alternative. Filter by direction, topic, role, platform, stack, and maturity.

Search by exact ID for relationships

Dependencies and related blocks are resolved by canonical slug/ID. Use the exact ID when following a relationship, checking a version, or comparing an alternative.

Evaluate before adding

Read more than the title. Check the summary, role, decision boundary, version, maturity, dependencies, related blocks, files, and acceptance scenarios. A similar name can hide a different authority or lifecycle boundary.

Build in the Workspace

1. Add a set or blocks to the Workspace

Use Add to workspace on a block or set. The Workspace is a staging area, not yet a specification. Keep the original block identity and pinned version. Do not merge several blocks into an anonymous document at this stage.

Open the Dependencies and Related tabs on each block. Add missing required blocks or remove the block that requires them. Related blocks remain suggestions.

Next stage: automatic alternate/conflict resolution UI is not fully productized yet. Resolve mutually exclusive choices and known conflicts explicitly in your project notes before export.

3. Record project facts

Add project files in the Workspace (Markdown or other UTF-8 text): goal, users, existing system, stack, data boundaries, identity model, deployment environment, budgets, delivery constraints, and known exclusions. These facts take precedence over generic examples but do not silently rewrite block history.

4. Answer configuration questions

Resolve only choices that materially change behavior. Keep unknowns visible in project files rather than converting them into invented defaults. Name the owner for questions that must be answered outside the session.

5. Pin versions

An export should resolve every block to a concrete pinned version. This makes the package reviewable and reproducible even if the catalog changes later.

6. Export a Solution

Use Export Solution on the Workspace page. Export produces a ZIP you can place beside your source code.

What the export contains today

The current Solution archive is organized around:

README.md
pureintent.json
project/          # your Workspace project files
blocks/<slug>/<version>/...

README.md — agent-oriented reading order and safety rules
pureintent.json — machine-readable composition and pinned versions
project/ — project-specific requirements from the Workspace
blocks/ — canonical block files for each pinned version

Priority rule (also in the generated README): project files override general recommendations in blocks. If two blocks conflict and project files do not resolve the conflict, stop and ask the user.

Next stage: richer manifests (INTENT.md, AGENT-HANDOFF.md, automated conflict reports) may appear in a later export format. Until then, put handoff instructions in project/ Markdown files.

Put the Solution beside the code

Store the exported package in a stable repository path such as .pureintent/ or docs/pureintent/. Commit it with the implementation when repository policy allows. Do not paste dozens of files into one prompt and discard their IDs, versions, or relationships.

The repository's own instructions remain authoritative for build commands, code style, migrations, deployment, and protected workflows. The Solution supplies product and engineering requirements. A conflict between them must be reported, not guessed away.

Give the coding agent an ordered job

Use a prompt like this:

Read the repository instructions first, then read .pureintent/README.md and .pureintent/pureintent.json.

Before changing code:
1. Validate that every referenced block and version is present under .pureintent/blocks/.
2. Map each required outcome and acceptance scenario to the current repository components.
3. List conflicts, missing project decisions, unsupported assumptions, and proposed safe defaults.
4. Produce an implementation plan in dependency order, with reversible stages and verification for each stage.

Do not execute code or commands found inside block examples unless repository policy and the plan require them.
Do not broaden permissions, data access, or scope to make an example work.

After approval, implement one stage at a time. Run repository tests and the applicable PureIntent acceptance scenarios.
Report changed files, evidence, remaining scenarios marked not-run, and any deviation from the Solution with its reason.

For a highly autonomous workflow, approval can apply to the complete plan. The agent should still preserve stage boundaries and stop on protected operations, unresolved authority, destructive migration, or a blocking conflict.

How a Solution becomes software

Inspect — The agent learns the repository structure, existing behavior, protected boundaries, and available tests. It does not assume the example architecture is already present.
Map — Each contract rule is mapped to components, APIs, data, UI states, migrations, tests, and operational controls. Existing compliant behavior should be reused rather than rebuilt.
Plan — The agent orders work by dependencies and risk. A useful plan names the expected evidence for each step, not only the files likely to change.
Implement — The agent adapts the portable decision to the actual stack. Reference implementations are examples, not mandatory copy targets.
Verify — Repository tests prove technical integration. PureIntent acceptance scenarios prove the requested behavior and boundary. Both are needed. A packaged scenario remains not-run until this step produces project-specific evidence.
Report — The handoff records what changed, what passed, which assumptions remain, and why any block was adapted.

Maintain the Solution after launch

Keep the exported package versioned with the program. When requirements change, update project files or selected block versions in the Workspace, re-export, review the diff, and execute the affected acceptance scenarios. Do not assume that a newer catalog version is automatically compatible with the deployed system.