@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/int-writing-agents/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: int-writing-agents
+metadata:
+  spindle:
+    version: 1.0.0
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+---
+
+# Writing Custom Agents
+
+Write focused, reusable agent definitions, not editor setup guides. Use `int-writing-for-agents` skill for the instruction body.
+
+## Workflow
+
+### 1. Define the role
+
+Read nearby definitions and applicable instructions. Identify purpose, inputs, allowed actions, output, and stopping condition. Confirm the intended harness before adding harness-specific fields.
+
+**Complete when:** role and invocation needs are explicit; harness-dependent requirements are resolved or blocked.
+
+### 2. Create or revise the file
+
+Use `.github/agents/<topic>.agent.md` for workspace agents. Preserve unrelated behavior. Write optional YAML between `---` delimiters, followed by Markdown instructions.
+
+Every frontmatter field is optional in the VS Code format. Include useful `name` and task-specific `description` fields for identification and discovery; name defaults to the filename. Add only needed fields:
+
+| Need          | Authoring contract                                                                                                                                                                                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Tool access   | Use supported tools for the intended harness. In Local, `tools: ['read', 'search']` supports repository inspection; `tools: []` grants none. Omission uses enabled tools, not zero tools.                                                                          |
+| Model         | Omit `model` to preserve the selected default; use confirmed available names only when requested.                                                                                                                                                                  |
+| Hidden worker | Set `user-invocable: false`; keep `disable-model-invocation: false` (the default) for normal worker discovery. Visibility and delegation are separate controls.                                                                                                    |
+| Delegation    | In Local, include the `agent` tool set. Restrict workers with an `agents` allowlist of exact, case-sensitive names; omission or `['*']` allows all, `[]` prevents delegation. An explicit entry overrides that worker's `disable-model-invocation: true` in Local. |
+| Handoff       | Local handoffs transition the conversation, unlike subagent delegation. Each entry requires `label`, `agent`, and `prompt`; use `send: false` for user review before submission.                                                                                   |
+
+Use current invocation fields instead of deprecated `infer`. Keep instruction-file fields such as `applyTo` out of agent frontmatter. `target` is not a harness selector; `mcp-servers` is for Copilot cloud agents, not VS Code agents. Check the [file reference](https://code.visualstudio.com/docs/agents/reference/custom-agent-file-reference) for additional fields and harness compatibility.
+
+**Complete when:** fields, tools, invocation controls, and targets match the role and harness.
+
+### 3. Write the body
+
+State task, inputs, bounded workflow, output shape, and completion condition. Match actions to tools. Link guidance relative to the agent file. Example:
+
+```markdown
+---
+name: Contract Reviewer
+description: Review request/response contracts without changing files.
+tools: ["read", "search"]
+---
+
+Review the contract paths identified by the caller.
+Read relevant definitions, handlers, and tests.
+Return evidence-backed findings with severity and file references.
+If scope or evidence is missing, identify the missing input.
+Stop after covering the supplied paths or reporting the blocker.
+```
+
+**Complete when:** scope, capabilities, output, and stopping condition are actionable.
+
+### 4. Validate
+
+Check location, YAML syntax, field names, references, tools, and agent identifiers. For behavior-shaping changes, use the `int-testing-agent-guidance` skill to establish a baseline and exercise a representative task; inspect output and tool use. Distinguish static checks from untested runtime discovery or invocation.
+
+**Complete when:** evidence supports claims; unverified runtime requirements are explicit.
+
+For creation context, see [Custom agents in VS Code](https://code.visualstudio.com/docs/agent-customization/custom-agents).

package/build/Assets/Blueprints/skills/int-writing-for-agents/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: int-writing-for-agents
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.1.1
+---
+
+# Writing for agents
+
+Shared Reference guidance for writing any document an agent consumes: a Skill, an Agent's instruction body, a project Instruction, or a document reached by a pointer. It covers wording and information hierarchy, not an authoring workflow. Aim for reliable application; the same wording does not guarantee the same behavior across models or hosts.
+
+When writing a Skill, choosing its invocation, or designing a router, use the `int-writing-skills` skill for Skill structure, frontmatter, visibility, and the authoring workflow.
+
+For behavior-shaping edits, use the `int-testing-agent-guidance` skill to establish a baseline and verify the revised guidance.
+
+## Context pointers
+
+A **context pointer** names out-of-context material and the condition for reaching it. A Skill description and an Instruction naming a reference are both pointers. Wording helps determine retrieval, but availability and host behavior matter too. For required material behind a weak pointer, sharpen the condition first; inline it only if retrieval still fails.
+
+A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word**: the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+Example: replace "See the release docs" with "When preparing a release, follow `docs/release-checks.md`." The latter names both the branch and the action; the reference keeps ownership of the checks.
+
+## The two loads
+
+Documents and pointers spend two budgets:
+
+- **Context load** is the cost of material in the agent's window: tokens and attention. Always-loaded Instructions and discovery descriptions spend it even when irrelevant; a disclosed document spends it when loaded. The host determines what is loaded and when.
+- **Cognitive load** is the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise: it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Disclosure defers the body's context load, not eliminates it. An unreferenced document leaves the human responsible for finding and supplying it.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** is the primary tier: what the agent does, in order.
+2. **In-file reference** is consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung), which is a fine arrangement, not a smell.
+3. **Disclosed reference** is pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** moves material out of the main file and behind a pointer so the common path stays legible. Inline what every branch needs; disclose what only some branches reach. For example, a release Skill keeps tests and changelog checks inline, but points database releases to `docs/database-release.md`.
+
+**Co-location** decides what sits together once its tier is chosen. Keep a concept's definition, rules, and caveats under one heading, so a lookup brings the relevant constraints with it. Scattering fragments one meaning across headings; duplication repeats that meaning.
+
+**Sprawl** is a document too long for reliable application, even when every line is unique. Disclose by branch or sequence when that improves application; file length alone does not establish a failure.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity**: can the agent tell done from not-done? Replace "understanding reached" with "Every affected module is listed with its path, impact, and supporting evidence." A vague bound can invite **premature completion**. Sharpen it first; only if it remains irreducibly fuzzy _and_ you observe rushing should you consider hiding the **post-completion steps**. A split hides them only if the host actually removes them from the executing context; a hand-off or subagent alone is not proof of isolation.
+- **Demand**: how much it requires. "Every modified model accounted for" sets a stronger bar than "produce a change list." Demand specifies **legwork**, the digging required within the task. It also applies to flat reference: "every applicable rule checked" sets an exhaustiveness bar without prescribing a sequence.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence**: consider a split when observed premature completion persists after sharpening the criterion. Verify that the split actually isolates later steps and improves the same scenario; otherwise keep the sequence together.
+- **By invocation**: create a separate Skill when it needs independent discovery or explicit invocation by callers. Otherwise a conditionally disclosed reference file may be sufficient. Use the `int-writing-skills` skill to choose invocation and visibility.
+
+## Leading words
+
+A **leading word** is a compact term used consistently to name a behavior or concept. Familiar terms may help retrieval, but their meaning is model- and task-dependent. Define the intended meaning beside its rules; use shorthand only when it preserves the constraints.
+
+The same term can connect a pointer to its body. That is a hypothesis to test in retrieval and application scenarios, not a guarantee from pretraining.
+
+For example, **red** can name an observed failing test when that meaning is defined. **Tight** cannot replace "fast, deterministic, low-overhead" without losing independently checkable requirements.
+
+Prefer a positive target when it makes the action clearer: "For release work, follow the release-checks reference" instead of "Don't forget the docs." Keep explicit prohibitions when needed for hard guardrails, paired with the permitted action. **Negation** does not universally cause the forbidden behavior; verify wording against the actual task.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** (the same meaning in more than one place) costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too (`package.json` scripts, config files, the directory layout, `--help` output), and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** through subtraction: run the same task with and without the candidate guidance, checking observable behavior through `int-testing-agent-guidance`. A passing run without it does not prove irrelevance across other tasks or models. Remove a sentence when the comparison supports that decision; preserve required contracts and guardrails. If wording fails, sharpen the action or criterion rather than merely adding a stronger adjective.

package/build/Assets/Blueprints/skills/int-writing-instruction/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: int-writing-instruction
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Writing Copilot Instructions
+
+## Overview
+
+Use workspace instruction files to give Copilot concise, durable project guidance that does not belong in every task prompt. Put targeted files in `.github/instructions/**/*.instructions.md`; this skill covers writing and organizing them, not enabling them in VS Code.
+
+## Choose Scope and Files
+
+- Keep repository-wide guidance directly in `.github/instructions/`. Put package-specific guidance under `.github/instructions/packages/<package>/`, following the relevant source area when scopes differ. For example, orchestration controller guidance lives at `packages/orchestration/app/inertia-pages.instructions.md`, while test guidance lives under `packages/orchestration/tests/`.
+- Name each file for its topic and end it in `.instructions.md`. Keep its `applyTo` pattern scoped to the source files the rules govern; the instruction file's directory is for organization, not a substitute for that glob.
+- Make each file about one coherent topic or area, such as frontend conventions, API design, or tests.
+- Split files when their rules apply to different code areas or tasks. A single broad file with conditional rules makes irrelevant guidance load and obscures which rules apply.
+- Use a narrow `applyTo` pattern for file-specific conventions. Use `**` only when every workspace file genuinely needs the guidance.
+- Keep repository requirements consistent with other applicable instructions. Sources can be additive; do not rely on file order or precedence to resolve conflicts.
+- Do not repeat rules that are already clear in another instruction file or reliably enforced by project tooling.
+
+## Frontmatter
+
+All three fields are optional. Add only fields that improve discovery or scope:
+
+| Field         | Purpose                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------- |
+| `name`        | Display name shown in the UI; defaults to the file name.                                                  |
+| `description` | Describes tasks where the instructions are relevant, supporting task-based discovery.                     |
+| `applyTo`     | Workspace-relative glob that automatically attaches the file when matching files are created or modified. |
+
+Use `description` when the guidance is useful for a task even if no matching file is open. Use `applyTo` when guidance is tied to files. Both may be useful together. If neither is present, the file must be attached manually.
+
+```markdown
+---
+name: Python tests
+description: Use when creating or changing Python tests, including when no test file is open.
+applyTo: "**/*test*.py"
+---
+
+# Python Tests
+
+- Reuse the fixtures and assertion style from nearby tests because they encode project conventions.
+- Test observable behavior and important edge cases; keep each test focused on one outcome.
+```
+
+Keep the body short and self-contained. State one actionable expectation per bullet and explain the reason when it helps Copilot handle edge cases. Show a concrete preferred pattern when a rule is otherwise ambiguous. Use `/` in paths and patterns.
+
+## Validate
+
+For behavior-shaping changes, use `int-testing-agent-guidance` to establish a baseline and try the same representative task with the revised guidance. Check the response's References to confirm the instruction was included, then inspect the work and tool activity for adherence. Discovery alone does not show that the guidance shaped the result.
+
+For current VS Code behavior and frontmatter details, consult [Use custom instructions in VS Code](https://code.visualstudio.com/docs/agent-customization/custom-instructions).

package/build/Assets/Blueprints/skills/int-writing-skills/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: int-writing-skills
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.3.0
+---
+
+# Writing Skills
+
+Author reusable guidance by testing the current behavior, addressing the observed gap, and retesting. This is an Interactive skill.
+
+**REQUIRED:** Use the `int-writing-for-agents` skill for shared writing principles and the `int-testing-agent-guidance` skill for test execution. This skill owns Skill structure, frontmatter, visibility, invocation, routers, and the authoring workflow.
+
+## Authoring flow
+
+On entering each node, announce `Step <node ID> - <node label>` before acting. Announce resumed steps and loop re-entries; state each decision result and selected branch. For nested flowcharts, use the [hierarchical announcement protocol](./references/interactive-skills.md#flowchart-protocol).
+
+```mermaid
+flowchart TD
+    A[Choose scope and type] --> B[Test current guidance]
+    B --> C{Gap observed?}
+    C -- No --> H[Report no change needed]
+    C -- Yes --> D[Load type guidance and write]
+    D --> E[Test revised guidance]
+    E --> F{Scenario passes?}
+    F -- No --> D
+    F -- Yes --> G[Refactor and deliver]
+    G -- Wording changed --> E
+```
+
+Complete each phase before continuing; track its applicable completion criteria as todos.
+
+### A. Choose scope and type
+
+A skill teaches a reusable capability. Put project conventions in instructions, one-off solutions in the task, and mechanically enforceable rules in tooling.
+
+Choose the primary type:
+
+- **Interactive:** ordered actions with completion criteria and progressively disclosed supporting material. Human input is required only where requested.
+- **Reference:** knowledge consulted and applied as needed, organized for lookup. Examples and short procedures may support it.
+
+Mixed content chooses its primary purpose, not a third type. Type is independent of visibility and invocation.
+
+**Internal visibility:** name internal skills with `int-` and use exactly this description, instead of discovery triggers:
+
+```text
+This is an internal skill do not load it unless explicitly required by the user or another skill.
+```
+
+An internal skill is like a private method or class: a primary skill pulls it in at an explicit disclosure point. It may be Interactive or Reference and may have only one caller. Keep invocation by another skill available; `user-invocable: false` hides the slash command without disabling that route.
+
+For non-internal, model-discoverable skills, start descriptions with "Use when..." and name concrete triggers, not workflow. Human-only skills use `disable-model-invocation: true` and a human-facing description. Follow the [Agent Skills specification](https://agentskills.io/specification): use a lowercase, hyphenated name matching its directory, a description of at most 1,024 characters, and repository version metadata.
+
+**Invocation:** [VS Code's controls](https://code.visualstudio.com/docs/agent-customization/agent-skills#use-skills-as-slash-commands) separate slash-menu visibility from automatic discovery:
+
+| Intended access                                                    | Configuration                                                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Slash command and automatic discovery                              | Omit both controls; use concrete discovery branches in the description                                     |
+| Internal, explicitly requested by a caller; hidden from slash menu | Set `user-invocable: false`; use the internal description above and leave `disable-model-invocation` unset |
+| Human-only slash command                                           | Set `disable-model-invocation: true`; use a human-facing description and leave `user-invocable` unset      |
+| Neither slash command nor automatic discovery                      | Set both controls                                                                                          |
+
+`description` is required in every case. Automatic discovery does not imply slash-menu visibility. These are VS Code's documented routes, not a universal guarantee of explicit loading or context cost across hosts. Verify caller invocation in the target host; when unavailable, use a plain reference file with an explicit pointer.
+
+**Routers:** a router Skill gives the human one entry point naming target Skills and the conditions for choosing each. For human-only targets, direct the human to invoke the target rather than executing it automatically: "For release preparation, invoke `/release-checks`. To publish, choose `/publish` yourself." Executing other Skills requires a verified host-supported loading route and targets intended for that route.
+
+Apply **DRY**: keep each meaning authoritative in one place; reuse existing guidance through explicit pointers. Apply **YAGNI**: include only what the requested capability needs. Internal skills enable disclosure, not speculative abstractions.
+
+**Complete when:** reusable scope, primary type, visibility, invocation, and relevant prior art are explicit.
+
+### B. Test current guidance
+
+Before drafting or editing, read [Testing skills](./references/testing-skills.md) and run the baseline. **No skill without a failing test first.** If drafted before RED, discard the draft and restart from the baseline.
+
+**Complete when:** a frozen scenario, observable criterion, and baseline result are recorded.
+
+### C. Gap observed?
+
+Compare the recorded behavior with the criterion. A specific failure selects Yes and D; a passing baseline selects No and H.
+
+**Complete when:** the result and selected branch are explicit.
+
+### D. Load type guidance and write
+
+Load only the selected branch:
+
+- **Interactive:** read [Interactive skills](./references/interactive-skills.md).
+- **Reference:** read [Reference skills](./references/reference-skills.md).
+
+Use the matching template named there for every new skill. For existing skills, adopt its structure only where relevant to the requested edit. Address the observed gap using the guidance form selected during testing.
+
+Store skills at `.github/skills/<skill-name>/SKILL.md`. Keep that entry file at the skill root; put supporting documentation in `references/` and output templates in `assets/`:
+
+```text
+skill-name/
+├── SKILL.md
+├── references/    - documentation loaded when needed
+└── assets/        - templates and other files used in output
+```
+
+Keep the common path inline; disclose branch-specific material through conditional pointers. Internal skills are another disclosure boundary when explicitly invoked guidance is appropriate.
+
+**Complete when:** the selected structure is filled, references resolve, each retained section has a distinct purpose, and no placeholder remains.
+
+### E. Test revised guidance
+
+Rerun the same frozen scenario in a fresh context using the `int-testing-agent-guidance` skill and the selected criteria in [Testing skills](./references/testing-skills.md).
+
+**Complete when:** revised behavior and any remaining failures are recorded.
+
+### F. Scenario passes?
+
+Compare observed behavior with the unchanged criterion. An unresolved failure selects No and D for a targeted correction; a passing scenario selects Yes and G.
+
+**Complete when:** evidence supports the stated result and selected branch.
+
+### G. Refactor and deliver
+
+Prune duplication, stale material, and speculative rules. Retest after wording changes. Verify frontmatter, relative links, resource packaging, and any required version bump. Run expanded testing only when requested, including `--test`.
+
+**Complete when:** final validation passes or limitations are explicit, and the change is ready for authorized delivery. Commit, push, or open a PR only when requested.
+
+### H. Report no change needed
+
+Leave passing behavior unchanged. Report the scenario and evidence without inventing a gap.
+
+**Complete when:** the user has the baseline result and reason no revision is needed.

package/build/Assets/Blueprints/skills/int-writing-skills/assets/interactive.md

@@ -0,0 +1,83 @@
+# Interactive skill template
+
+Replace every `[placeholder text]` slot. Apply the common metadata and visibility rules in the primary authoring skill. Keep the optional flowchart only when the workflow has a non-obvious branch or loop; adapt its nodes and matching step headings together.
+
+````markdown
+---
+name: [skill-name]
+description: "[description appropriate to visibility and invocation]"
+---
+
+# [Skill title]
+
+[Purpose, scope, and concrete applicability.]
+
+## [Optional argument contract]
+
+[If this skill accepts arguments, add argument-hint to frontmatter and define accepted inputs using the Arguments reference. Specify required and optional inputs, paired long/short flags, defaults, values, parsing boundaries, validation, and workflow effects. Validate before workflow actions. Otherwise omit this section and argument-hint.]
+
+## Workflow
+
+[Required guidance for all paths, if any.]
+
+On entering each node, announce `Step <node path> - <label path>` before acting. Announce resumed steps and loop re-entries; state each decision result and selected branch. For sub-flowcharts, use dot-separated ancestor IDs and labels separated by `/`.
+
+```mermaid
+flowchart TD
+    A[Establish scope] --> B[Perform work]
+    B --> C{Result meets criteria?}
+    C -- No --> B
+    C -- Yes --> D[Report result]
+```
+
+### A. Establish scope
+
+[Actions that establish the required inputs and intended result.]
+
+**Complete when:** [Checkable, exhaustive scope criterion.]
+
+### B. Perform work
+
+[Actions using the established scope. At a branch-specific need, require loading its supporting reference or internal skill and state the trigger.]
+
+**Complete when:** [Checkable, exhaustive work criterion.]
+
+### C. Result meets criteria?
+
+[Evaluate the result against the criterion; state the result and selected branch.]
+
+**Complete when:** [Evidence supports either returning to B or proceeding to D.]
+
+### D. Report result
+
+[Required output, evidence, and unresolved limitations.]
+
+**Complete when:** [The delivered result and validation evidence meet the requested contract.]
+
+## [Optional sub-flowchart title]
+
+Parent: [Full parent node path and label path]. Enter when [observable condition]. Local node IDs below extend the parent path in announcements.
+
+```mermaid
+flowchart TD
+    A[Inspect evidence] --> B[Assess evidence]
+```
+
+### [Parent path].A. Inspect evidence
+
+[Child action.]
+
+**Complete when:** [Checkable child criterion.]
+
+### [Parent path].B. Assess evidence
+
+[Child action and exit condition. On exit, announce the parent as resumed and continue at the stated return point without repeating completed child work.]
+
+**Complete when:** [Child exit criterion and exact parent return point.]
+
+## [Optional example]
+
+[One adaptable example. Use pseudocode for language-neutral illustrative code; actual language only for a skill always specific to it. Commands and required formats keep their syntax.]
+````
+
+Remove unused optional sections. If the flowchart is omitted, replace node-based headings with ordered steps and omit its announcement instruction. A retained sub-flowchart requires a real parent call site and matching return point. Add repository-required version and invocation metadata before delivery.

package/build/Assets/Blueprints/skills/int-writing-skills/assets/reference.md

@@ -0,0 +1,32 @@
+# Reference skill template
+
+Replace every `[placeholder text]` slot. Apply the common metadata and visibility rules in the primary authoring skill. Repeat topic sections only for distinct lookup needs; remove optional sections that do not apply.
+
+```markdown
+---
+name: [skill-name]
+description: "[description appropriate to visibility and invocation]"
+---
+
+# [Subject]
+
+[Covered knowledge, applicability, and relevant version or environment boundaries.]
+
+## [Lookup topic]
+
+[Precise facts or contract: inputs, outputs, constraints, and failure behavior where relevant. Keep caveats beside the fact they qualify.]
+
+## [Conditional topic pointer, if needed]
+
+When [observable feature or environment condition], read [supporting reference or explicitly required internal skill] for [knowledge needed only in that case].
+
+## [Application example]
+
+[One valid, adaptable example that applies the documented contract, with real syntax or pseudocode clearly identified.]
+
+## [Authoritative sources]
+
+[Source links or environment lookups needed to establish or refresh the facts.]
+```
+
+Add repository-required version and invocation metadata before delivery.

package/build/Assets/Blueprints/skills/int-writing-skills/references/arguments.md

@@ -0,0 +1,50 @@
+# Arguments
+
+Load when authoring an Interactive skill that accepts arguments, whether supplied by a user or explicitly by another skill. Argument support is optional; within an argument-accepting skill, individual inputs may be required or optional.
+
+## Define the contract
+
+Put `argument-hint` in frontmatter to advertise syntax. Define behavior in the skill body before workflow actions; the hint alone does not parse or validate inputs.
+
+Specify:
+
+- Accepted flags and positional inputs, each marked required or optional.
+- Both a long name and a unique, case-sensitive single-letter short alias for every flag, with identical behavior: for example, `--test` / `-T`.
+- Whether each flag is a switch or takes a value, its accepted values, and its default when omitted.
+- How each input changes workflow branches or output. For example, a test option adds expanded checks while ordinary checks still run.
+- Parsing rules, validation failures, and repeated or conflicting option behavior.
+
+A calling skill supplies inputs explicitly. Use declared defaults for omissions; conversational mentions elsewhere are not arguments.
+
+## Parsing defaults
+
+Use these defaults for skills accepting free-form task text. If a capability needs different rules, state the replacement explicitly in its contract.
+
+1. Parse only the leading option prefix. Recognize exact declared long and short forms; short aliases are individual tokens, not bundles such as `-TF`. Case variants are different names.
+2. A value-taking flag consumes the next token as its value. Validate that token before continuing; a missing value or another option in its place requires correction. Support forms such as `--format=json` only if explicitly declared.
+3. `--` ends option parsing and is not part of task text. Otherwise, the first non-option token starts the task. Preserve the remaining task text unchanged, including later flag-like text; remove only the separating whitespace before the task.
+4. Reject unknown leading flags, unsupported values, and repeated options, including repetition through aliases. Never silently choose between conflicting values.
+5. Validate required inputs after parsing. Explain each invalid or missing input and request correction before performing workflow actions.
+
+For structured caller inputs, validate the same names, values, requirements, and defaults without reconstructing a command string. Any supplied raw argument string follows the same parsing contract as user input.
+
+## Example
+
+A skill accepting required task text and optional testing and output controls could advertise:
+
+```yaml
+argument-hint: "[--test|-T] [--format|-F <text|json>] [--] <task>"
+```
+
+Its body declares `--test` / `-T` as a switch defaulting off and `--format` / `-F` as a value-taking option defaulting to `text`, with `text` and `json` accepted. Testing enables expanded checks in addition to ordinary checks; format selects the report shape.
+
+| Input                                         | Parsed result                                                 |
+| --------------------------------------------- | ------------------------------------------------------------- |
+| `-T --format json investigate --test in logs` | Testing on, JSON output; task is `investigate --test in logs` |
+| `-- --test is task text`                      | Defaults; task is `--test is task text`                       |
+| `--format`                                    | Request a value and required task text before work            |
+| `--format text -F json investigate`           | Request one format choice before work                         |
+
+Render the selected contract into the authored skill; its executing agent should not need this authoring reference.
+
+**Complete when:** accepted inputs have unambiguous semantics, invalid input stops before work, and tests exercise aliases, defaults, parsing boundaries, and correction paths.

package/build/Assets/Blueprints/skills/int-writing-skills/references/interactive-skills.md

@@ -0,0 +1,53 @@
+# Interactive skills
+
+Use this branch when the skill primarily directs the agent through work. Interaction means agent action, not mandatory conversation with a human.
+
+## Structure and disclosure
+
+For a new skill, load and fill the [Interactive template](../assets/interactive.md). For an existing skill, apply it only to the relevant edit.
+
+- Put purpose and applicability before ordered actions. End each action with a checkable, exhaustive completion criterion.
+- Keep what every path needs in `SKILL.md`. Put branch-specific guidance behind a pointer beside the action that needs it; name the observable condition that requires loading it.
+- Co-locate a concept's definition, rules, and caveats. Use `int-writing-for-agents` skill for the shared writing principles rather than restating them.
+- Use a small flowchart for a non-obvious branch or loop, with simple action labels and short decision labels. Keep diagram nodes, step headings, branch targets, and completion criteria consistent.
+- Add quick reference and common mistakes only when they serve a distinct need. Aim below 500 words when reliable at that length.
+
+## Optional arguments
+
+Argument support is optional. When the skill accepts arguments from a user or a calling skill, read [Arguments](./arguments.md) and define its contract before workflow actions. For skills without arguments, omit the argument contract and `argument-hint`.
+
+## Flowchart protocol
+
+Every Interactive skill with a flowchart must instruct the executing agent to announce **before acting** on each node:
+
+```text
+Step <node path> - <label path> [optional task context]
+```
+
+Announce initial entries, resumed steps, and loop re-entries. After evaluating a decision, state its result and selected branch before entering the target node. Task context may identify a review mode or work item; it does not replace the node path.
+
+### Sub-flowcharts
+
+Each sub-flowchart declares its parent node and the condition for entering it. IDs are local to each diagram; announcements use the full dot-separated ancestor path. Labels use the same order, separated by `/`.
+
+For example, a primary node `C[Verify skill]` can disclose a child diagram with local node `A[Run focused scenario]`:
+
+```text
+Step C - Verify skill
+Step C.A - Verify skill / Run focused scenario
+Step C.A.B - Verify skill / Run focused scenario / Assess result
+```
+
+The third line illustrates a further child `B` under `C.A`. Declare that parent explicitly too. Repeat the full path at every depth, including decision results and branch targets, so reused local IDs remain unambiguous.
+
+Define each child exit and its return point in the parent. When a child finishes, announce the parent as resumed and continue after the child call; do not restart completed child work. A child loop stays within the child until its exit criterion is met.
+
+The authoring skill's own announcement instruction is an instance of this protocol. In an authored skill, render the protocol into its execution instructions so the agent can follow that skill without loading authoring guidance.
+
+## Examples
+
+Use one complete, adaptable example when it helps application. For illustrative code, use **pseudocode** unless the skill is always specific to one programming language; then use that language. Executable commands and required formats such as YAML and Mermaid retain their actual syntax.
+
+## Completion
+
+The workflow is usable without loading unrelated branches; every action has an observable end; diagrams and announcements preserve parent/child context; examples match the skill's language scope. Use [Testing skills](./testing-skills.md) to select an application scenario, not merely a prose review.