Skip to content

Commit 44db3b7

Browse files
ashleyshawashleyshaw
committed
Update instruction files
1 parent faf7950 commit 44db3b7

21 files changed

+942
-287
lines changed

‎.github/agents/task-researcher.agent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
name: "Task Researcher"
2+
name: "Task Researcher Agent"
33
description: "Research aggregation, validation, and evidence generation for WordPress block theme planning tasks."
44
target: "github-copilot"
55
version: "v1.0"

‎.github/agents/template.agent.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: "Template: Agent Specification"
3+
description: "Reusable LightSpeedWP agent spec template covering role, behaviours, tooling, schemas, safety, and validation for block-theme-scaffold."
4+
version: "v1.1"
5+
last_updated: "2025-12-11"
6+
owners: ["LightSpeedWP Engineering"]
7+
tags: ["agent", "spec", "template", "copilot", "block-theme"]
8+
status: "draft"
9+
apply_to: [".github/agents/*.agent.md"]
10+
file_type: "template"
11+
tools: ["Copilot Agents"]
12+
references:
13+
- "AGENTS.md"
14+
- ".github/agents/agent.md"
15+
- ".github/instructions/agent-spec.instructions.md"
16+
- ".github/instructions/copilot-ai-agent.instructions.md"
17+
- ".github/instructions/block-theme-development.instructions.md"
18+
- ".github/workflows/block-theme-build-and-e2e.yml"
19+
metadata:
20+
guardrails: "Agents must never perform destructive or irreversible actions without explicit confirmation."
21+
---
22+
23+
# Template Usage
24+
25+
- Copy this file to `.github/agents/{{agent_slug}}.agent.md`.
26+
- Replace `{{placeholders}}` with the agent's values; keep the section order.
27+
- Link the spec to its script, prompt, workflow, and tests in the **Repository Mapping** table.
28+
- Align guardrails with `.github/instructions/agent-spec.instructions.md`, `AGENTS.md`, and security policy.
29+
30+
## Copyable Frontmatter (update per agent)
31+
32+
```yaml
33+
---
34+
title: "{{agent_title}}"
35+
description: "{{agent_summary}}"
36+
version: "{{agent_version}}"
37+
last_updated: "{{last_updated}}"
38+
owners: ["{{owner}}"]
39+
tags: ["agent", "{{team}}", "{{domain}}"]
40+
status: "{{status}}"
41+
apply_to: [".github/agents/{{agent_slug}}.agent.md"]
42+
runtime: "{{runtime_or_host}}"
43+
entrypoint: "{{script_path_or_command}}"
44+
tools:
45+
- run_in_terminal
46+
- read_file
47+
- file_search
48+
references:
49+
- "AGENTS.md"
50+
- ".github/instructions/agent-spec.instructions.md"
51+
- ".github/prompts/{{agent_slug}}.prompt.md"
52+
- ".github/workflows/{{agent_workflow}}.yml"
53+
metadata:
54+
guardrails: "{{short_guardrail_summary}}"
55+
---
56+
```
57+
58+
# Repository Mapping
59+
60+
| Area | Path/ID placeholder | Notes |
61+
| -------- | -------------------------------------------- | ----------------------------------------- |
62+
| Spec | `.github/agents/{{agent_slug}}.agent.md` | This file |
63+
| Prompt | `.github/prompts/{{agent_slug}}.prompt.md` | Input patterns, required variables |
64+
| Script | `scripts/{{agent_slug}}.agent.js` | Implementation/entrypoint |
65+
| Tests | `tests/agents/{{agent_slug}}.agent.test.js` | Validation suite (unit/integration) |
66+
| Workflow | `.github/workflows/{{agent_workflow}}.yml` | CI trigger for build/lint/e2e |
67+
| Reports | `.github/reports/agents/{{date}}-{{slug}}.*` | Logs/outputs written by the agent |
68+
69+
# 1. Role & Scope
70+
71+
- **Role:** `{{agent_role}}`
72+
- **Scope:** `{{boundaries_and_context}}` (block-theme-first; prefers `theme.json`, block components, and patterns)
73+
- **Supported systems:** `{{systems_repos_apis}}`
74+
- Clarify what the agent must decline (out-of-scope repos, infra, billing, deployments).
75+
76+
# 2. Responsibilities & Capabilities
77+
78+
- List allowed actions (`{{capabilities}}`) and explicit stops (`{{limitations}}`).
79+
- Note block theme preferences: use `theme.json`, blocks, patterns, and template parts; avoid bespoke PHP unless necessary.
80+
- Include automation rules, defaults, and required confirmations.
81+
82+
# 3. Allowed Tools & Integrations
83+
84+
- Enumerate tools and permissions (GitHub scopes, CLI commands, internal scripts).
85+
- List required env vars (names only) and data classification rules.
86+
- If a tool is not listed, the agent must treat it as unavailable.
87+
88+
# 4. Input Specification
89+
90+
- Define accepted inputs: natural language + structured payloads (JSON/YAML/forms).
91+
- Provide JSON Schema where structure matters; include mustache variables for templated prompts.
92+
- Add concrete examples for happy path and edge cases.
93+
94+
# 5. Output Specification
95+
96+
- Specify required output shape (success/warning/error) with deterministic fields.
97+
- Formatting rules (Markdown, JSON blocks, tables) and parsing needs.
98+
- Include log references/paths when outputs produce artifacts.
99+
100+
# 6. Safety Guardrails
101+
102+
- Non-negotiable prohibitions: no secrets, no destructive actions without confirmation, no production mutations without approval.
103+
- Refuse tasks outside scope; prefer read-only for diagnostics.
104+
- Escalation/approval rules and rate/moderation limits.
105+
- Block theme constraint: do not bypass build/lint workflows; prefer declarative changes.
106+
107+
# 7. Failure & Rollback Strategy
108+
109+
- How to respond to invalid inputs, missing context, and failing tools.
110+
- Steps for partial success handling and rollback expectations or limitations.
111+
- Recovery defaults (for example restore from git; never delete user files to recover).
112+
113+
# 8. Test Tasks (for Validation)
114+
115+
- Provide three minimal tasks with expected results:
116+
- **Typical task** → expected behaviour and outputs.
117+
- **Edge case** → safe handling and confirmations required.
118+
- **Failure case** → deterministic error/rollback response.
119+
- Reference the workflow or test file that validates these behaviours.
120+
121+
# 9. Observability & Logging
122+
123+
- Required logs: timestamps, tool calls, external interactions, decisions.
124+
- Storage locations: `logs/agents/{{date}}-{{slug}}.log`, `.github/reports/agents/{{date}}-{{slug}}.*`.
125+
- Metrics/audit rules and privacy notes (do not store secrets/PPI).
126+
127+
# 10. Changelog
128+
129+
- Keep an ordered list of spec changes with version and date.
130+
- Example: `v1.1 (2025-12-11) – Updated guardrails; clarified rollback behaviour; aligned with block-theme-scaffold.`

‎.github/instructions/README.md‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,26 @@ category: Project
55
type: Index
66
audience: Developers, AI Assistants
77
date: 2025-12-01
8+
applyTo: ".github/instructions/README.md"
89
---
910

1011
# Development Instructions
1112

12-
This directory contains detailed instructions and guidelines for AI-assisted development.
13+
You are an instruction index curator. Follow our block theme scaffold documentation map to route Copilot to the right instruction sets. Avoid duplicating standards here—link to the dedicated instruction files instead.
14+
15+
## Overview
16+
17+
This directory lists the instruction files that guide Copilot and contributors working on the block theme scaffold. Use it to discover the right topic-specific instructions; it does not replace the detailed guidance in each file.
18+
19+
## General Rules
20+
21+
- Treat this file as a directory index, not a source of standards.
22+
- Link to topic-specific instructions rather than re-stating them.
23+
- Keep file names and paths up to date when instructions move or are added.
24+
25+
## Detailed Guidance
26+
27+
See the file list below for topic coverage. Open the relevant `*.instructions.md` file for the full rules, examples, validation steps, and references.
1328

1429
## Files
1530

@@ -32,15 +47,19 @@ This directory contains detailed instructions and guidelines for AI-assisted dev
3247
- **copilot-ai-agent.instructions.md** - AI agent workflows and rules
3348
- **generate-theme.instructions.md** - Theme generation instructions
3449

35-
## Purpose
50+
## Examples
51+
52+
- Use `wpcs-php.instructions.md` when editing PHP or adding new hooks.
53+
- Open `theme-json.instructions.md` before modifying design tokens or global styles.
54+
- Reference `reporting.instructions.md` when generating lint/test reports.
3655

37-
These instructions help AI tools understand:
56+
## Validation
3857

39-
- WordPress theme development best practices
40-
- Coding standards and conventions
41-
- Testing requirements and patterns
42-
- Configuration file structures
58+
- Confirm links resolve to existing files in `.github/instructions/`.
59+
- Run `rg --files .github/instructions` to ensure the index reflects current contents.
4360

44-
## Usage
61+
## References
4562

46-
Instructions are automatically loaded by AI development tools to provide context-aware assistance throughout the development process.
63+
- `.github/custom-instructions.md`
64+
- `.github/instructions/instructions.instructions.md`
65+
- `.github/agents/agent.md`

‎.github/instructions/a11y.instructions.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,48 @@ license: "GPL-3.0"
1111

1212
# Accessibility Standards for WordPress Block Themes
1313

14-
All code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
14+
You are an accessibility compliance assistant. Follow our WCAG 2.2 AA and WordPress block theme patterns to build, audit, and refactor accessible layouts. Avoid bespoke UI controls or ARIA hacks that diverge from native block behaviours unless explicitly required.
15+
16+
## Overview
17+
18+
Apply these instructions whenever adding or modifying markup, patterns, template parts, or interactions that affect accessibility. They focus on WCAG 2.2 AA compliance within WordPress block themes and do not replace broader security or performance guidelines.
19+
20+
## General Rules
21+
22+
- All code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
23+
- Prefer native block controls and semantics over custom widgets.
24+
- Maintain proper heading hierarchy and landmark structure in templates and patterns.
25+
- Provide perceivable focus states and keyboard operability for every interactive element.
26+
27+
## Detailed Guidance
28+
29+
- Use semantic HTML and block patterns; avoid div-only structures.
30+
- Keep ARIA usage minimal and purposeful; never use ARIA to patch invalid HTML.
31+
- Ensure text contrast meets 4.5:1 (text) and 3:1 (graphics/UI).
32+
- Supply meaningful alt text and labels for form elements.
33+
34+
## Examples
35+
36+
```html
37+
<!-- Good: semantic structure with labelled control -->
38+
<section aria-labelledby="contact-heading">
39+
<h2 id="contact-heading">Contact Us</h2>
40+
<label for="email">Email</label>
41+
<input id="email" type="email" name="email" required />
42+
</section>
43+
```
44+
45+
## Validation
46+
47+
- Automated: run axe-core or Lighthouse; ensure no critical violations.
48+
- Manual: keyboard navigation (Tab/Shift+Tab/Esc) and visible focus.
49+
- Screen readers: spot-check with VoiceOver/NVDA for form labels and landmarks.
50+
51+
## References
52+
53+
- [WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/)
54+
- `.github/instructions/html-markup.instructions.md`
55+
- `.github/instructions/block-theme-development.instructions.md`
1556

1657
## Quick Reference
1758

‎.github/instructions/agent-spec.instructions.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
description: "Instructions for creating, formatting, and reviewing agent specification files in block-theme-scaffold"
3+
applyTo: ".github/agents/*.agent.md"
4+
version: 1.0
5+
lastUpdated: 2025-12-11
6+
owner: "LightSpeedWP Engineering"
7+
---
8+
9+
# Agent Spec Instructions
10+
11+
You are an agent specification author for the LightSpeed block theme scaffold. Follow this guide to produce deterministic, auditable `.agent.md` specs using the template at `.github/agents/template.agent.md`. Keep scope tight, prefer block-first solutions, and treat every listed tool as an explicit permission.
12+
13+
## Overview
14+
15+
Use this instruction file when drafting or reviewing any `.agent.md` in `.github/agents`. Specs must describe how agents operate within a block-theme-first WordPress workflow, linking to their prompts, scripts, tests, and workflows.
16+
17+
## General Rules
18+
19+
- Start with value, then clarity, then governance: define purpose, make IO deterministic, then enforce guardrails.
20+
- Keep scope explicit: what the agent owns, what it refuses, and which repos/APIs it can touch.
21+
- Design for determinism: consistent outputs, clear error handling, and default-safe behaviours.
22+
- Front-load guardrails: non-negotiable safety, confirmation rules, and escalation paths.
23+
- Treat tools as permissions: if a tool is not listed, the agent must ignore it.
24+
- Use mustache placeholders (`{{agent_slug}}`, `{{agent_version}}`, etc.) in templates and prompts.
25+
- Align with block theme conventions: prefer `theme.json`, block components, patterns, and template parts over bespoke PHP.
26+
27+
## Structure & Frontmatter
28+
29+
- Copy the frontmatter pattern from `.github/agents/template.agent.md`.
30+
- Required fields: `title`, `description`, `version`, `last_updated`, `owners`, `tags`, `status`, `apply_to`, `runtime`, `entrypoint`, `tools`, `references`, and `metadata.guardrails`.
31+
- Keep references up to date: spec path, prompt, script, workflow, and related instructions.
32+
- Do not embed secrets or real environment variable values; list names only.
33+
34+
## Authoring Steps
35+
36+
1. Copy `.github/agents/template.agent.md` to `.github/agents/{{agent_slug}}.agent.md`.
37+
2. Replace placeholders with the agent’s details and block-theme context.
38+
3. Map the spec to its prompt, script, tests, and workflow in the repository mapping table.
39+
4. Define role, scope, capabilities, tools, input/output schemas, guardrails, failure handling, and observability.
40+
5. Add three validation tasks (typical, edge, failure) with expected behaviours.
41+
6. Update the changelog within the spec when you revise it.
42+
43+
## Inputs and Outputs
44+
45+
- Specify accepted natural-language inputs plus any structured schemas (JSON/YAML/forms).
46+
- Provide examples and, where structure matters, a JSON Schema.
47+
- Define deterministic output shapes for success, warnings, and errors, including required fields for automation.
48+
49+
## Safety & Guardrails
50+
51+
- Prohibit secret handling, destructive actions, and production mutations without explicit human confirmation.
52+
- Require adherence to build/lint/test workflows (`block-theme-build-and-e2e.yml`) before changes ship.
53+
- Escalate when tasks exceed scope or missing approvals; prefer read-only diagnostics.
54+
55+
## Tools & Integrations
56+
57+
- Enumerate every allowed tool or integration (GitHub scopes, CLI commands, internal scripts).
58+
- List required environment variable names; never include values.
59+
- If a tool is missing from the list, the agent must assume it is unavailable.
60+
61+
## Observability & Logging
62+
63+
- Require logging of timestamps, tool calls, external interactions, and key decisions.
64+
- Point logs to `logs/agents/YYYY-MM-DD-{{agent_slug}}.log` and reports to `.github/reports/agents/`.
65+
- Include audit and privacy notes; avoid storing secrets or personal data.
66+
67+
## Validation
68+
69+
- Confirm all placeholders are replaced and references resolve to real files.
70+
- Ensure the three validation tasks cover: normal flow, edge-case handling, and failure response.
71+
- Keep output formats parseable and consistent with downstream automation.
72+
- When applicable, align agent behaviour with tests in `tests/agents/{{agent_slug}}.agent.test.js` and workflows in `.github/workflows/`.
73+
74+
## Effective Spec Tips
75+
76+
- Keep scope extremely clear: name owned repos, workflows, and forbidden areas.
77+
- Make outputs deterministic: defined shapes, explicit error formats, and safe defaults.
78+
- Front-load guardrails: precise, enforceable, and testable constraints.
79+
- Treat each tool as a permission; omit tools the agent must not use.
80+
- Use realistic test tasks drawn from LightSpeed block-theme workflows.
81+
82+
## Review Checklist
83+
84+
- [ ] Purpose is unambiguous; boundaries are explicit.
85+
- [ ] Capabilities match supported workflows; limitations are stated.
86+
- [ ] All tools/integrations are listed with required auth notes.
87+
- [ ] Inputs/outputs are defined with examples and error formats.
88+
- [ ] Safety rules include confirmations and align with security policy.
89+
- [ ] Failure/rollback behaviour is documented.
90+
- [ ] Three validation tasks cover typical, edge, and failure cases.
91+
- [ ] Observability requirements (logs/reports) are included.
92+
- [ ] Changelog updated and references (prompt/script/tests/workflow) are accurate.
93+
94+
## References
95+
96+
- `.github/agents/template.agent.md`
97+
- `.github/agents/agent.md`
98+
- `.github/instructions/instructions.instructions.md`
99+
- `.github/instructions/copilot-ai-agent.instructions.md`
100+
- `.github/workflows/block-theme-build-and-e2e.yml`

‎.github/instructions/block-theme-development.instructions.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ description: "Comprehensive best practices and guidance for developing WordPress
44
applyTo: "**/*.{php,html,json,css,scss,js,jsx,ts,tsx}"
55
---
66

7+
# Block Theme Development Instructions
8+
9+
You are a block theme implementation guide. Follow our block-first scaffold standards to design, extend, and refactor WordPress block themes. Avoid classic PHP templates, editing built assets, or bypassing the theme.json-driven workflow.
10+
711
## Overview
812

913
> ⚠️ **Scope Notice**: These instructions are intended for **WordPress block theme
@@ -21,6 +25,18 @@ development standards. It references specialised instruction files in the
2125
`block-theme/` subdirectory and links to the WordPress Coding Standards in the
2226
`wpcs/` subdirectory.
2327

28+
## General Rules
29+
30+
- Always prefer block-first solutions (patterns, template parts, template composition) over classic PHP templates.
31+
- Keep business logic in PHP (`inc/`, `functions.php`) and presentation in blocks/patterns.
32+
- Do not edit built assets; change source files and rebuild.
33+
- Align styles and spacing with `theme.json` tokens instead of ad-hoc CSS.
34+
- Run lint, test, and build steps before commit or release.
35+
36+
## Detailed Guidance
37+
38+
The numbered sections below cover structure, build process, theme.json usage, enqueuing, patterns, accessibility, standards, documentation, scripts, external references, and reminders specific to this scaffold.
39+
2440
---
2541

2642
## 📂 Related Instruction Files
@@ -333,3 +349,23 @@ Add `.editorconfig` for consistent indentation and formatting.
333349
> - `.github/instructions/` — All organisation instruction files
334350
>
335351
> This ensures you are following the most up-to-date and project-specific guidelines.
352+
353+
## Examples
354+
355+
- Pattern registration snippet (`register_block_pattern`) in the "Pattern Development" section demonstrates naming, metadata, and content.
356+
- Template usage example (`<!-- wp:pattern {"slug":"lsx/home-template"} /-->`) in "Using Patterns in Templates."
357+
358+
## Validation
359+
360+
- Run `npm run lint`, `npm run test`, and `npm run build` before merging changes.
361+
- Validate block comments in templates/parts and pattern metadata headers.
362+
- Check `theme.json` changes against the WordPress schema (e.g., VS Code schema validation).
363+
364+
## References
365+
366+
- `.github/instructions/theme-json.instructions.md`
367+
- `.github/instructions/wpcs-php.instructions.md`
368+
- `.github/instructions/javascript.instructions.md`
369+
- `.github/instructions/wpcs-css.instructions.md`
370+
- `.github/instructions/html-markup.instructions.md`
371+
- `.github/custom-instructions.md`

0 commit comments

Comments
 (0)