docs: document undocumented scripts, HVE Builder workflow, and planner state schemas

.github/instructions/hve-core/hve-builder.instructions.md

@@ -57,6 +57,25 @@ Treat delegation as a first-class architecture decision, not an afterthought. Be
 * Design the loop explicitly: define dispatch inputs, owned evidence, return schema, stage gate, and which later step consumes the result. Parallelize only independent work.
 * Reuse before authoring. Survey the available subagents, skills, and instruction files. Prefer reusing an existing artifact as it stands; when it almost fits, prefer adjusting or extending it; create a new artifact only when no existing one can be reasonably adapted.
 
+## Skill-Forward Orchestrator Architecture
+
+Reusable behavior that must work both directly and under a parent belongs in a user-invocable skill by default. Author the skill first, then add a wrapper only when a user needs an entry point the skill alone does not provide. Do not build one large agent that carries the workflow and then expose a second path into the same logic.
+
+| Responsibility                                                           | Artifact                     | Control                                                       |
+|--------------------------------------------------------------------------|------------------------------|---------------------------------------------------------------|
+| Reusable workflow and domain capability, invoked directly or by a parent | Skill                        | `user-invocable: true`                                        |
+| Thin user-facing coordination over one or more skills                    | Agent or prompt wrapper      | `disable-model-invocation: true` when it must not be a worker |
+| Convention that applies whenever matching paths are edited               | Path-scoped instruction file | `applyTo` glob                                                |
+| Isolated, parallel, fresh-context, tool-specific, or model-specific work | Subagent                     | `user-invocable: false` when background-only                  |
+
+Keep the wrapper thin: it sequences skills, holds user-facing state, and reports. It does not restate the phase protocols, gates, or evidence rules the skill already owns.
+
+Standalone-versus-parent differences belong in the shared skill contract, not in a duplicate workflow. A standalone run advises the next action; a parent consumes the same skill return and owns continuation. Optional orchestrator inputs may narrow delegated work, but they must not turn one artifact into two materially different workflows.
+
+Treat an agent that is both user-invocable and dispatchable as a subagent as an exception. It qualifies only when both contexts share all six of purpose, inputs, outputs, interaction model, write authority, and safety contract. When any one diverges, split the artifact: put the shared behavior in a skill and give each context its own thin entry point.
+
+The current RPI structure is the reference example. RPI Agent coordinates the lifecycle without duplicating phase protocols. The `rpi-research`, `rpi-plan`, `rpi-implement`, and `rpi-review` skills carry behavior that works the same way directly and under that parent. RPI Researcher and RPI Planner stay bounded background-only workers.
+
 ## Load-Timing and Authority Routing
 
 For every rule or fact an artifact would carry, place it where it loads at the right time and binds with the right force. This keeps always-loaded surfaces short and moves enforcement off advisory prose.
@@ -216,6 +235,7 @@ Every item applies to the whole file. Mark an item not applicable when it does n
 * [ ] File structure and frontmatter follow the File Types and Frontmatter Requirements for the artifact type.
 * [ ] Each fact sits at the right load timing and authority; always-loaded surfaces stay short and non-inferable.
 * [ ] Delegation is used where it isolates or right-sizes work, and existing subagents, skills, and instructions are reused before new ones are created.
+* [ ] Behavior needed both directly and under a parent lives in one user-invocable skill; wrappers stay thin and no workflow logic is duplicated across a standalone and an orchestrated path.
 * [ ] Connected artifacts agree on modes, stage gates, result vocabulary, and terminal outcomes.
 * [ ] Existing non-tool capability-bearing frontmatter is preserved unless approved, verified evidence supports a Major, behavior-tested change.
 * [ ] Each model declaration uses the exact ordered list for its responsibility-selected profile; any override or proxy run is narrow and disclosed.
@@ -243,6 +263,7 @@ Remove these on sight when improving or replacing an artifact. Each is supersede
 * Response prefilling for output shaping on model families that no longer support it; use direct instructions, structured outputs, or post-processing.
 * JSON mode as a substitute for schema-constrained structured outputs where structured outputs are supported.
 * Kitchen-sink instruction files, copied style guides, copied templates, and exhaustive edge-case lists. Prefer scoped, referenced, evaluation-informed artifacts.
+* Workflow logic duplicated between a standalone path and an orchestrated path, or a single agent carrying two materially different contracts for direct and parent-dispatched use. Move the shared behavior into one user-invocable skill and keep each entry point thin.
 * Singular AGENT.md where AGENTS.md is the current format; keep a compatibility link where needed.
 * Universal secondhand length ceilings. Use the host's own published numbers and scope or defer the rest.
 * Fixed iteration counts used as quality theater rather than responses to observed findings.

docs/contributing/ai-artifacts-common.md

@@ -3,7 +3,7 @@ title: 'AI Artifacts Common Standards'
 description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
 sidebar_position: 2
 author: Microsoft
-ms.date: 2026-07-15
+ms.date: 2026-07-28
 ms.topic: reference
 ---
 
@@ -657,7 +657,7 @@ See [official documentation](https://example.com) for details.
 
 * Starts with frontmatter (YAML between `---` delimiters)
 * Followed by markdown content
-* Omits attribution suffix from the `description` field (added automatically at distribution)
+* Omits any attribution suffix from the `description` field
 * Single newline at EOF
 
 ## RFC 2119 Directive Language

docs/contributing/custom-agents.md

@@ -3,7 +3,7 @@ title: 'Contributing Agents to HVE Core'
 description: 'Requirements and standards for contributing GitHub Copilot agent files to hve-core'
 sidebar_position: 5
 author: Microsoft
-ms.date: 2026-07-15
+ms.date: 2026-07-28
 ms.topic: how-to
 ---
 
@@ -535,7 +535,7 @@ Before submitting your agent, verify:
 * [ ] Core directives with RFC 2119 keywords
 * [ ] Examples wrapped in XML-style blocks
 * [ ] Success criteria defined
-* [ ] Attribution footer present
+* [ ] Attribution footer absent
 
 ### Common Standards
 

docs/contributing/instructions.md

@@ -3,7 +3,7 @@ title: 'Contributing Instructions to HVE Core'
 description: 'Requirements and standards for contributing GitHub Copilot instruction files to hve-core'
 sidebar_position: 3
 author: Microsoft
-ms.date: 2026-07-15
+ms.date: 2026-07-28
 ms.topic: how-to
 ---
 
@@ -575,7 +575,7 @@ Before submitting your instructions file, verify:
 * [ ] Code examples wrapped in XML-style blocks
 * [ ] Anti-patterns section with alternatives
 * [ ] Validation/testing requirements
-* [ ] Attribution footer present
+* [ ] Attribution footer absent
 
 ### Code Examples
 

docs/contributing/prompts.md

@@ -3,7 +3,7 @@ title: 'Contributing Prompts to HVE Core'
 description: 'Requirements and standards for contributing GitHub Copilot prompt files to hve-core'
 sidebar_position: 4
 author: Microsoft
-ms.date: 2026-07-08
+ms.date: 2026-07-28
 ms.topic: how-to
 ---
 
@@ -537,7 +537,7 @@ Before submitting your prompt, verify:
 * [ ] Workflow steps with clear sequence
 * [ ] Success criteria defined
 * [ ] Error handling documented
-* [ ] Attribution footer present
+* [ ] Attribution footer absent
 
 ### Workflow Definition
 
@@ -568,6 +568,61 @@ Before submitting your prompt, verify:
 * [ ] Compatible with existing prompts/workflows
 * [ ] Does not duplicate existing prompt functionality
 
+## Authoring with the HVE Builder Skill
+
+The `hve-builder` skill is the lifecycle entrypoint for prompts, instruction files,
+agents, subagents, and skills. It applies the standards on this page, dispatches
+independent review, runs behavior testing when a change warrants it, and resolves a
+single overall outcome. Prefer it over hand-editing when you are creating a new prompt
+or making a behavior-bearing change to an existing one.
+
+Activate it by asking for the work in natural language, optionally naming the mode.
+There is no slash command; `hve-builder` is a skill, not a prompt.
+
+### Modes
+
+| Mode       | Write authority              | Use when                                                     |
+|------------|------------------------------|--------------------------------------------------------------|
+| `create`   | Creates new source artifacts | The target prompt does not exist yet                         |
+| `improve`  | Edits existing source        | An existing prompt needs new or corrected behavior           |
+| `refactor` | Edits existing source        | Cleanup must preserve current behavior                       |
+| `replace`  | Rewrites existing source     | The artifact needs wholesale replacement                     |
+| `review`   | Read-only; writes evidence   | You want static and behavior findings without source changes |
+| `validate` | Read-only; writes evidence   | You want host validation results only                        |
+
+The skill infers the narrowest safe mode when you do not name one, and asks only when
+plausible modes would grant materially different write authority.
+
+### Compatibility aliases
+
+Three alias skills preserve legacy activation phrasing and route straight to
+`hve-builder`. They add no second author, test, or evaluation loop.
+
+| Alias skill       | Routes to                              |
+|-------------------|----------------------------------------|
+| `prompt-builder`  | `hve-builder` in `create` or `improve` |
+| `prompt-analyze`  | `hve-builder` in read-only `review`    |
+| `prompt-refactor` | `hve-builder` in `refactor`            |
+
+Each alias translates its legacy `promptFiles` input to the `hve-builder` `targets`
+input. New work should name `hve-builder` and its mode directly.
+
+### Behavior testing
+
+`hve-builder` delegates behavior testing to `hve-builder-tester`, which is the sole
+behavior-testing entrypoint. Behavior testing runs for major mutations and for
+behavior-bearing review targets, and is legitimately skipped for eligible minor and
+medium changes.
+
+### Evidence
+
+Runs write author, review, behavior-test, and validation evidence under
+`.copilot-tracking/hve-builder/{{YYYY-MM-DD}}/` unless you supply a different evidence
+root. Read-only modes change nothing else.
+
+Authoring standards for all artifact kinds live in
+`.github/instructions/hve-core/hve-builder.instructions.md`.
+
 ## Testing Your Prompt
 
 See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For prompts specifically:

docs/contributing/skills.md

@@ -3,7 +3,7 @@ title: Contributing Skills to HVE Core
 description: Requirements and standards for contributing skill packages to hve-core
 sidebar_position: 6
 author: Microsoft
-ms.date: 2026-06-30
+ms.date: 2026-07-28
 ms.topic: how-to
 keywords:
   - skills
@@ -101,11 +101,11 @@ The `scripts/` directory is **optional**. When present, it **MUST** contain at l
 
 **`description`** (string, MANDATORY)
 
-| Property | Value                                                                                             |
-|----------|---------------------------------------------------------------------------------------------------|
-| Purpose  | Concise explanation of skill functionality                                                        |
-| Format   | Single sentence describing the skill; no attribution suffix (added automatically at distribution) |
-| Example  | `'Video-to-GIF conversion skill with FFmpeg two-pass optimization'`                               |
+| Property | Value                                                               |
+|----------|---------------------------------------------------------------------|
+| Purpose  | Concise explanation of skill functionality                          |
+| Format   | Single sentence describing the skill; no attribution suffix         |
+| Example  | `'Video-to-GIF conversion skill with FFmpeg two-pass optimization'` |
 
 ### Frontmatter Example
 

docs/customization/build-system.md

@@ -2,7 +2,7 @@
 title: Build System and Validation
 description: Understand the plugin generation pipeline, schema validation system, npm scripts, and CI checks for customizing and extending HVE Core
 author: Microsoft
-ms.date: 2026-07-16
+ms.date: 2026-07-28
 ms.topic: how-to
 keywords:
   - build system
@@ -62,6 +62,33 @@ The `scripts/linting/schemas/schema-mapping.json` file defines the glob-to-schem
 Patterns are evaluated from most specific to least specific, and the first match determines
 the schema. When no pattern matches, `base-frontmatter.schema.json` applies as the default.
 
+### Planner State Schemas
+
+The same `scripts/linting/schemas/` directory also holds JSON Schemas for planner session
+state. These validate the `state.json` files that phase-based planning agents persist under
+`.copilot-tracking/`. They are not frontmatter schemas, so they are not listed in
+`schema-mapping.json` and are not exercised by `npm run lint:frontmatter`.
+
+| Schema                            | Validates                                                    |
+|-----------------------------------|--------------------------------------------------------------|
+| `accessibility-state.schema.json` | `.copilot-tracking/accessibility/{project-slug}/state.json`  |
+| `rai-state.schema.json`           | `.copilot-tracking/rai-plans/{project-slug}/state.json`      |
+| `security-state.schema.json`      | `.copilot-tracking/security-plans/{project-slug}/state.json` |
+| `sssc-state.schema.json`          | `.copilot-tracking/sssc-plans/{project-slug}/state.json`     |
+
+Each schema is the source of truth for its planner's required keys, field types, enum
+values, and defaults. Agent and instruction files show illustrative state snippets with
+JSON-literal defaults; when a snippet and its schema disagree, the schema wins.
+
+Two enforcement paths cover these schemas:
+
+* Editor validation through the `json.schemas` entries in `.vscode/settings.json`, which
+  bind the RAI and accessibility state paths to their schemas as you edit.
+* Pester coverage in `scripts/tests/linting/Test-PlannerStateSchemas.Tests.ps1` and
+  `scripts/tests/linting/Test-AccessibilityStateSchema.Tests.ps1`, which validate schema
+  fixtures and guard the inline state examples in agent and instruction files against
+  drift. Run them with `npm run test:ps -- -TestPath "scripts/tests/linting/"`.
+
 ### Adding Custom Schemas
 
 To add validation for a new file type: