Scaffold a Grounded Declarative Agent from a Business Brief

A template can generate files. It cannot decide whether “HR policy” means the approved policy library or every document HR has ever uploaded. The useful part of WIQD scaffolding is turning a business brief into boundaries you can review, validate, and test before the first provision.

Ask Your CLI for the Business Brief

The scenario starts inside the organization, not with an empty manifest. I asked my CLI to find the approved brief that the People Operations team had already discussed and stored in Microsoft 365.

That one paragraph is the scenario from start to finish. Work IQ supplied the organizational context, including the owner and approved source. The coding agent’s next job was not to invent a project. It was to convert that paragraph into an explicit specification.

This is how lifecycle orientation chooses the create path: WIQD sees no agent project, identifies Build as the current phase, and routes the request to agent-create. If the folder already contained an agent, the same request would go through agent-edit instead of overwriting a project.

Trace Requirements into Reviewable Artifacts

Requirement translation means every important sentence gets an enforcement point. It also means not asking one artifact to do another artifact’s job.

Business requirement	Artifact	What enforces it
Employees get policy answers	appPackage/instructions.txt	Defines the supported tasks and response workflow
Compensation and performance are refused	appPackage/instructions.txt	Defines prohibited topics and escalation behavior
Answers use only approved policies	declarativeAgent.json	Scopes OneDriveAndSharePoint to one library and discourages model knowledge
Every policy claim is cited	appPackage/instructions.txt	Requires a citation and a no-source fallback
Users know what to ask	conversation_starters	Offers tasks supported by the instructions and knowledge source
App IDs differ by environment	env/.env.*	Supplies deployment values without hardcoding them in manifests
Manifest references stay valid	.github/lsp.json and validation	Surfaces schema and cross-file diagnostics

The generated baseline is deliberately boring:

hr-policy-guide/
├── .github/lsp.json
├── appPackage/
│   ├── color.png
│   ├── declarativeAgent.json
│   ├── instructions.txt
│   ├── manifest.json
│   └── outline.png
├── env/
│   ├── .env.dev
│   └── .env.local
├── .gitignore
├── m365agents.local.yml
└── m365agents.yml

The Microsoft 365 app manifest is the app shell. The declarative agent manifest connects instructions, capabilities, and starters. m365agents.yml drives lifecycle operations, environment files provide non-secret values, and the LSP configuration enables live diagnostics.

External instructions matter because behavior is prose, and prose deserves a clean pull-request diff:

# Purpose
You are the HR Policy Guide for Contoso employees.

# Supported tasks
- Answer questions about leave, workplace conduct, remote work, travel
  expenses, and benefits enrollment.
- Use only the configured Published Policies knowledge source.

# Boundaries
- Do not answer questions about individual compensation or performance.
- For a prohibited or unsupported request, explain the boundary and direct
  the employee to HR Support through the internal help portal.
- Do not infer policy details that are absent from the approved source.

# Response format
- Lead with a concise answer.
- Cite the source document for every policy claim.
- If no source supports the answer, say that the approved policies do not
  contain enough information and use the escalation path.

In a separate file, reviewers can challenge a scope boundary without decoding escaped newlines in JSON. The manifest remains structural; the instructions remain readable and versioned.

The manifest makes that relationship explicit and discourages answers from the model’s built-in knowledge:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json",
  "version": "v1.8",
  "name": "HR Policy Guide",
  "description": "Answers employee questions from Contoso's approved HR policies.",
  "instructions": "$[file('instructions.txt')]",
  "behavior_overrides": {
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  }
}

Add Narrow SharePoint Grounding

The broad site URL from a browser tab would be https://contoso.sharepoint.com/sites/People. That includes drafts and working documents. The approved source is the PublishedPolicies library, so I asked for one narrow edit.

Omitting both items_by_url and items_by_sharepoint_ids would allow access to all SharePoint and OneDrive sources available to the user. A site URL would still exceed the approved library. A library URL makes the boundary visible and auditable in one line.

If a requested capability needs a newer schema, WIQD should report the mismatch before editing. Upgrade intentionally, review the schema changes, and validate again. Never downgrade the scaffolded schema to make it look familiar.

Keep Conversation Starters Honest

Starters are promises. Each one should represent a distinct supported task that the configured knowledge can answer.

"conversation_starters": [
  {
    "title": "Parental leave",
    "text": "What does our parental leave policy cover?"
  },
  {
    "title": "Remote work",
    "text": "What are the eligibility rules for remote work?"
  },
  {
    "title": "Travel expenses",
    "text": "Which travel expenses can I claim?"
  },
  {
    "title": "Benefits enrollment",
    "text": "When can I change my benefits enrollment?"
  }
]

These cover four different intents. None promises to update payroll, submit an expense, or retrieve a performance review because the agent has no action for those tasks. Delete any generated starter that advertises unsupported behavior.

Validate Before Provisioning

Validation is the boundary between Build and Improve. In this scenario, the first run caught a copied sharing URL with query parameters. I replaced it with the structural library URL and ran validation again:

$ wiqd agent validate
✓ appPackage/manifest.json
✓ appPackage/declarativeAgent.json
✓ appPackage/instructions.txt reference
✓ OneDriveAndSharePoint source URL
✓ conversation starters: 4 of 12

Validation passed: 0 errors, 0 warnings

That clean result proves schema shape and references, not behavior. The four-case smoke-test matrix is the next review artifact:

Case	Test question	Expected behavior
Answerable	What does the parental leave policy cover?	Answers from Published Policies and cites the source
Missing knowledge	Does the policy cover a new office benefit not in the library?	States that the source does not support an answer and escalates
Out of scope	What rating did my manager give me?	Refuses the performance request and directs the user to HR Support
Citation	What are the remote work eligibility rules?	Cites every policy claim and does not rely on model knowledge

Keep shared placeholders and non-secret settings in .env.local or .env.dev. Put credentials only in ignored .env.*.user files, confirm the ignore rule with git status, and never paste a sharing link containing access tokens into a manifest. Environment hygiene is part of the scaffold, not cleanup for later.

The agent is ready to enter Improve when the brief has an owner and escalation path, every requirement maps to an artifact, grounding matches the approved library, starters promise only supported tasks, validation is clean, no secrets are tracked, and the smoke-test expectations have an accountable reviewer.

The Value You Just Unlocked

• Organizational context becomes a specification: Work IQ retrieves the approved brief, owner, and source before generation starts.
• Boundaries become reviewable: Scope, refusals, citations, and escalation live in external instructions with readable diffs.
• Grounding becomes auditable: One library URL replaces broad, accidental access to a whole SharePoint site.
• Starters become honest contracts: Every suggested task is backed by the configured instructions and capability.
• Improve starts with evidence: Clean validation and four smoke tests replace “the scaffold ran” as the quality bar.

The first commit now explains not only what the agent contains, but why each artifact exists. That is the difference between a template dump and a technical baseline.

Resources

• WIQD create and edit workflows
• WIQD agent create command
• Add knowledge sources to declarative agents
• OneDrive and SharePoint manifest object
• Write effective instructions for declarative agents
• Declarative agent schema 1.8