Add persistent agent instruction file output mode (Copilot, Claude Code, Cursor)

bootstrap.md

@@ -34,6 +34,7 @@ You are the **composition engine** for PromptKit. Your job is to:
    - "I need to review this code for security vulnerabilities."
    - "I need an implementation plan for migrating our database."
    - "I need to design an extension framework for a verifier — let's reason through it interactively."
+   - "I want to create a persistent Copilot instruction file for my project."
 3. Based on the user's response, **select the appropriate template** and
    its associated persona, protocols, and format.
 4. **Check the template's `mode` field** in its YAML frontmatter:
@@ -43,15 +44,46 @@ You are the **composition engine** for PromptKit. Your job is to:
 5a. **Interactive mode**: Load the template's components (persona, protocols,
    format), then **execute the template directly in this session**. Begin
    the interactive workflow (e.g., ask clarifying questions, reason through
-   the design) — do NOT write a file. Skip steps 5b–8.
-5b. **Single-shot mode**: Ask for the required parameters defined in the
-   template's `params` field.
-6. **Ask where to save the output.** Before assembling, ask the user for a
-   file path where the assembled prompt should be written. Suggest a sensible
-   default (e.g., `./assembled-prompt.md` in the current working directory).
-7. **Load and assemble** the selected components by reading the referenced files.
-8. **Write the assembled prompt** to the user's chosen location.
-9. **Confirm** the file path and provide a brief summary of what was assembled.
+   the design) — do NOT write a file. Skip steps 5b–10.
+5b. **Single-shot mode**: Ask about the output mode before collecting
+   template parameters (since the chosen mode may switch the active template):
+   - **(a) Raw prompt** *(default)*: A Markdown file to load into a fresh
+     LLM session for this specific task. Keep the current template.
+   - **(b) Agent instruction file**: A persistent file automatically loaded
+     by an agent runtime (GitHub Copilot, Claude Code, Cursor, etc.) that
+     encodes the selected persona and protocols as reusable, standing
+     instructions. If the user chooses this mode:
+     - Ask which platform(s) they target: `GitHub Copilot`, `Claude Code`,
+       `Cursor`, or `All`.
+     - Switch to the `author-agent-instructions` template (if not already
+       selected) and set `platform` from the user's answer.
+     - The output file path is determined by the platform:
+
+       | Platform | Output path |
+       |----------|-------------|
+       | GitHub Copilot | `.github/instructions/<skill-name>.instructions.md` (one per skill) |
+       | Claude Code | `CLAUDE.md` |
+       | Cursor | `.cursorrules` |
+
+     - Assemble using the `agent-instructions` format. For GitHub Copilot,
+       produce composable skill files with YAML frontmatter (`description`,
+       `applyTo`). For other platforms, produce a single combined file.
+6. **Collect parameters.** Ask for the required parameters defined in the
+   active template's `params` field (this is the template selected in step 3,
+   or the `author-agent-instructions` template if the user chose output
+   mode (b) in step 5b).
+7. **Ask for the target project directory.** The output files must be written
+   to the **user's project**, not to the PromptKit repository. Ask the user
+   for the path to their target project root. Suggest a sensible default
+   based on the output mode:
+   - Raw prompt → `./assembled-prompt.md` (current directory)
+   - Agent instruction file → ask for the target project root, then use
+     platform-specific paths relative to it (e.g.,
+     `<project>/.github/instructions/<name>.instructions.md` for Copilot,
+     `<project>/CLAUDE.md` for Claude Code)
+8. **Load and assemble** the selected components by reading the referenced files.
+9. **Write the output** to the resolved path(s) in the user's target project.
+10. **Confirm** the file path(s) and provide a brief summary of what was assembled.
 
 ## Assembly Process
 
@@ -66,7 +98,8 @@ When assembling a prompt from components, follow this order:
 6. PARAMETERS — Substitute all {{param}} placeholders with user-provided values.
 ```
 
-The assembled prompt should read as a single coherent document, structured as:
+**Raw prompt output** (default): The assembled prompt reads as a single coherent
+document with PromptKit section headers:
 
 ```markdown
 # Identity
@@ -90,6 +123,22 @@ The assembled prompt should read as a single coherent document, structured as:
 <task-specific exclusions>
 ```
 
+**Agent instruction file output** (when user selects output mode (b) in step 6):
+Assemble the same components, then pass them through the `agent-instructions`
+format to produce platform-appropriate instruction files. For GitHub Copilot,
+this produces **composable skill files** under `.github/instructions/` — one
+per logical concern, each with YAML frontmatter specifying `description` and
+`applyTo` glob targeting. Each skill file:
+
+- Has YAML frontmatter with `description` and `applyTo`
+- Opens with `<!-- Generated by PromptKit — edit with care -->`
+- Contains condensed persona or protocol directives
+- Uses second-person directives throughout ("You are…", "When you encounter…")
+- Does **NOT** include PromptKit section headers (`# Identity`, `# Reasoning Protocols`, etc.)
+- Is self-contained and independently coherent
+
+For Claude Code and Cursor, a single combined file is produced instead.
+
 ## Pipeline Support
 
 Some tasks are part of a **pipeline** where the output of one template
@@ -108,6 +157,12 @@ When a user's task is part of a pipeline:
 
 - **Ask clarifying questions** when the user's task does not clearly map to
   a single template. Suggest the closest match and explain why.
+- **Suggest the agent instruction output mode** when the user's task is
+  recurring or project-wide (e.g., "always review my C code for memory safety").
+  Explain that outputting a persistent instruction file means the behavior is
+  automatically applied in every session, not just the current one. If they want
+  a standalone agent instruction file from scratch (not tied to a specific task
+  template), direct them to the `author-agent-instructions` template.
 - **Suggest interactive mode for complex tasks.** If the task is complex,
   ambiguous, or requires domain expertise, suggest an interactive template
   (e.g., `interactive-design`, `extend-library`) instead of a single-shot
@@ -133,7 +188,9 @@ When a user's task is part of a pipeline:
 - **Show your work.** Before presenting the assembled prompt, briefly explain
   which components you selected and why.
 
-## Example Interaction
+## Example Interactions
+
+### Raw Prompt Output (default)
 
 ```
 User: I need to investigate a potential use-after-free bug in our C networking code.
@@ -148,4 +205,29 @@ I am also adding the memory-safety-c protocol since you are working with C code
 and the issue involves use-after-free. Let me gather the parameters...
 
 What code or context can you provide? (source files, stack traces, logs, repro steps)
-```
+```
+
+### Agent Instruction File Output
+
+```
+User: I want a persistent instruction file so Copilot always reviews C code
+for memory safety in our project.
+
+Assistant: Great — that sounds like a recurring, project-wide behavior. Instead of a
+one-off prompt, I will produce a persistent agent instruction file.
+
+Based on your needs, I will assemble skill files using:
+- **Persona**: systems-engineer
+- **Protocols**: anti-hallucination + memory-safety-c
+- **Format**: agent-instructions
+- **Template**: author-agent-instructions
+- **Platform**: GitHub Copilot → `.github/instructions/`
+  - `systems-engineer.instructions.md` (persona + guardrails, applyTo: `**`)
+  - `memory-safety-c.instructions.md` (memory safety checks, applyTo: `**/*.c, **/*.h`)
+
+A few quick questions:
+1. What is the path to your target project? (e.g., `../my-networking-project`)
+2. Should I include the root-cause-analysis protocol as well?
+3. Are there any project-specific conventions I should embed
+   (e.g., preferred allocator, banned functions, coding standard)?
+```

formats/agent-instructions.md

@@ -0,0 +1,167 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) PromptKit Contributors -->
+
+---
+name: agent-instructions
+type: format
+description: >
+  Output format for persistent agent instruction files. Produces
+  composable skill files for GitHub Copilot
+  (.github/instructions/*.instructions.md) and platform-appropriate
+  equivalents for Claude Code and Cursor. Files are version-controlled
+  and automatically loaded by agent runtimes.
+produces: agent-instruction-file
+---
+
+# Format: Agent Instruction Files
+
+The output MUST be one or more ready-to-commit agent instruction files
+for the specified platform(s). For GitHub Copilot, each PromptKit
+protocol produces a **separate skill file** with an `applyTo` glob so
+skills compose automatically — mirroring PromptKit's own compositional
+architecture.
+
+Do NOT produce raw prompt output with PromptKit section headers — the
+content must be continuous, natural instruction prose suitable for direct
+consumption by the target agent runtime.
+
+## Output Structure
+
+### 1. File Manifest
+
+List every file that will be created:
+
+| Platform | File Path Pattern | Scope |
+|----------|-------------------|-------|
+| GitHub Copilot | `.github/instructions/<name>.instructions.md` | Per-skill (targeted via `applyTo`) |
+| Claude Code | `CLAUDE.md` | Project-wide |
+| Cursor | `.cursorrules` | Project-wide |
+
+For GitHub Copilot, produce **one skill file per logical concern**. The
+recommended decomposition is:
+
+| Skill file | Contents | `applyTo` example |
+|------------|----------|-------------------|
+| `<persona>.instructions.md` | Condensed persona identity and guardrail protocols (anti-hallucination, self-verification) | `**` |
+| `<analysis-protocol>.instructions.md` | A single analysis protocol's checks and phases | Language-specific glob (e.g., `**/*.c`) |
+| `<reasoning-protocol>.instructions.md` | A single reasoning protocol | `**` or task-specific glob |
+
+State which file(s) will be produced and why.
+
+### 2. File Content — GitHub Copilot Skill Files
+
+Each `.instructions.md` file MUST begin with YAML frontmatter:
+
+```markdown
+---
+description: '<one-line summary of what this skill does>'
+applyTo: '<glob pattern>'
+---
+
+<instruction content>
+```
+
+**Frontmatter fields:**
+
+- **`description`** *(required)* — A brief summary of the skill's purpose.
+  Wrap in single quotes.
+- **`applyTo`** *(required)* — Comma-separated glob patterns specifying
+  which files activate this skill. Use `**` for all files, or
+  language-specific patterns like `**/*.c, **/*.h`.
+
+**Content rules:**
+
+- Open with `<!-- Generated by PromptKit — edit with care -->` immediately
+  after the frontmatter closing `---`.
+- Write in **second person** ("You are…", "When you encounter…").
+- Condense protocol phases into standing directives — preserve all specific
+  checks but omit meta-commentary about protocol structure.
+- Do NOT include PromptKit-internal headers (`# Identity`,
+  `# Reasoning Protocols`, `# Output Format`, etc.).
+- Each skill file must be **self-contained** — it should make sense when
+  loaded independently by the agent runtime.
+
+### 3. File Content — Claude Code and Cursor
+
+For Claude Code (`CLAUDE.md`) and Cursor (`.cursorrules`), produce a
+**single combined file** containing all persona and protocol content
+(these platforms do not support per-file skill targeting).
+
+The content MUST:
+
+- Begin with `<!-- Generated by PromptKit — edit with care -->`
+- Contain all instructions as continuous, natural Markdown
+- Be complete and self-contained
+
+### 4. Platform Notes
+
+For each target platform, include a short note covering:
+
+- **How it is loaded**: when and how the platform reads the file(s)
+- **Known constraints**: size limits, unsupported syntax, scope restrictions
+- **Recommended maintenance**: how to update and test the instructions
+
+### 5. Activation Checklist
+
+A numbered checklist of steps to activate the instructions:
+
+1. Commit the file(s) to the repository.
+2. Reload the agent / editor extension.
+3. Verify the agent acknowledges the instructions in a test prompt.
+
+## Platform Reference
+
+### GitHub Copilot — `.github/instructions/*.instructions.md`
+
+- **Loaded automatically** by GitHub Copilot in VS Code, JetBrains, and
+  GitHub.com when editing files matching the `applyTo` glob.
+- **Scope**: Per-skill. Multiple skill files compose automatically;
+  all matching skills are combined for the current file context.
+- **Size guidance**: Keep each skill file under ~4 KB for reliable
+  ingestion. Total combined instructions should stay under ~8 KB.
+- **Naming**: Filenames must be lowercase, hyphen-separated, ending in
+  `.instructions.md` (e.g., `memory-safety-c.instructions.md`).
+- **Syntax**: Plain Markdown with YAML frontmatter. `description` and
+  `applyTo` are required frontmatter fields.
+- **Testing**: Open a Copilot Chat session while editing a file that
+  matches `applyTo` and ask "What instructions are active?" to confirm.
+
+### Claude Code — `CLAUDE.md`
+
+- **Loaded automatically** by Claude Code when it starts in a directory
+  that contains this file (project root or any parent).
+- **Scope**: Project-level (nearest `CLAUDE.md` takes precedence).
+- **Size guidance**: No hard limit documented; keep concise for best results.
+- **Syntax**: Plain Markdown. Claude Code reads the full file.
+- **Testing**: Start a Claude Code session and ask "What project context
+  do you have?" to verify the file is loaded.
+
+### Cursor — `.cursorrules`
+
+- **Loaded automatically** by Cursor as project-level rules applied to
+  all Cursor AI interactions within the workspace.
+- **Scope**: Project-level.
+- **Size guidance**: Keep under ~2 KB; Cursor may truncate longer files.
+- **Syntax**: Plain text or Markdown. Cursor reads the raw content.
+- **Testing**: Open Cursor in the repo and ask "What rules are you following?"
+
+## Formatting Rules
+
+- Do NOT include PromptKit-internal section headers in generated file
+  content (`# Identity`, `# Reasoning Protocols`, `# Output Format`, etc.).
+- Write instructions in **second person** directed at the agent
+  (e.g., "You are a…", "When reviewing code, always…").
+- Condense protocol and persona content — omit meta-commentary about the
+  protocol structure and retain only the actionable guidance.
+- Every section in each output file MUST be present; omit sections only
+  if the platform imposes a size constraint, and note which sections were
+  omitted.
+- Do NOT embed `{{param}}` placeholders in the output — all values must
+  be resolved before writing the file.
+- For GitHub Copilot, choose `applyTo` globs that match the protocol's
+  natural scope:
+  - Language-specific protocols → language file extensions
+    (e.g., `**/*.c, **/*.h` for `memory-safety-c`)
+  - Guardrail / reasoning protocols → `**` (all files)
+  - Domain-specific protocols → relevant path patterns
+    (e.g., `**/infra/**` for infrastructure review)

manifest.yaml

@@ -190,6 +190,15 @@ formats:
       Structured release notes with changelog, breaking changes, upgrade
       instructions, and contributor acknowledgment.
 
+  - name: agent-instructions
+    path: formats/agent-instructions.md
+    produces: agent-instruction-file
+    description: >
+      Output format for persistent agent instruction files. For GitHub
+      Copilot, produces composable skill files under
+      .github/instructions/*.instructions.md with applyTo targeting.
+      Also supports Claude Code (CLAUDE.md) and Cursor (.cursorrules).
+
 taxonomies:
   - name: stack-lifetime-hazards
     path: taxonomies/stack-lifetime-hazards.md
@@ -288,6 +297,18 @@ templates:
       persona: software-architect
       protocols: [anti-hallucination]
 
+  agent-authoring:
+    - name: author-agent-instructions
+      path: templates/author-agent-instructions.md
+      description: >
+        Assemble PromptKit components (persona, protocols) into composable
+        agent skill files. For GitHub Copilot, produces individual
+        .github/instructions/*.instructions.md files with applyTo targeting.
+        Also supports Claude Code (CLAUDE.md) and Cursor (.cursorrules).
+      persona: spl-contributor
+      protocols: [anti-hallucination, self-verification]
+      format: agent-instructions
+
   contribution:
     - name: extend-library
       path: templates/extend-library.md