From 4edc7ef4fce91edafecdccff3fc15dc023d2e2d2 Mon Sep 17 00:00:00 2001 From: "david.delagneau" Date: Tue, 14 Apr 2026 16:37:54 -0600 Subject: [PATCH] feat: Enhance AI prompting capabilities with new guidelines and templates for GitHub Copilot --- .opencode/agents/fidelity.md | 1 + .opencode/commands/copilot-prompt.md | 41 +++++++++++ .opencode/commands/fidelity-context.md | 1 + .opencode/plugins/fidelity-compaction.js | 1 + .../copilot-prompt-engineering/SKILL.md | 43 ++++++++++++ AGENTS.md | 2 + README.md | 3 + ai/AGENTS.md | 2 + ai/context/process/ai-to-ai-prompting.md | 69 +++++++++++++++++++ ai/context/process/index.md | 3 + opencode.json | 1 + prompts/copilot-prompt.md | 43 ++++++++++++ 12 files changed, 210 insertions(+) create mode 100644 .opencode/commands/copilot-prompt.md create mode 100644 .opencode/skills/copilot-prompt-engineering/SKILL.md create mode 100644 ai/context/process/ai-to-ai-prompting.md create mode 100644 prompts/copilot-prompt.md diff --git a/.opencode/agents/fidelity.md b/.opencode/agents/fidelity.md index 02381e0..a174f3e 100644 --- a/.opencode/agents/fidelity.md +++ b/.opencode/agents/fidelity.md @@ -33,4 +33,5 @@ Behavior rules: - Do not over-promote uncertain information. Keep uncertain items in the daily log. - When drafting communication, preserve technical meaning and improve clarity in natural US English. - When answering Swift/iOS programming questions, use the project-local iOS skills and `ai/context/ios/`. +- When generating prompts for GitHub Copilot or another AI, use `ai/context/process/ai-to-ai-prompting.md` and the `copilot-prompt-engineering` skill. - If the answer depends on current Apple APIs or Xcode/iOS behavior, verify with official Apple or Swift documentation before presenting it as current best practice. diff --git a/.opencode/commands/copilot-prompt.md b/.opencode/commands/copilot-prompt.md new file mode 100644 index 0000000..2151d8e --- /dev/null +++ b/.opencode/commands/copilot-prompt.md @@ -0,0 +1,41 @@ +--- +description: Generate a high-quality prompt for GitHub Copilot on the Fidelity development machine +--- + +Generate a prompt that the user can send to GitHub Copilot or another AI assistant on the Fidelity development machine. + +Read: + +@prompts/copilot-prompt.md +@ai/AGENTS.md +@ai/context/process/ai-to-ai-prompting.md +@ai/context/index.md +@ai/context/project.md +@ai/context/ios/index.md +@ai/context/ios/project-swift-guidance.md +@ai/context/systems/index.md +@ai/context/workstreams/index.md +@ai/work-items/index.md +@ai/state/current.md +@ai/state/work-items.md + +Detailed active work item files, if available: + +!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi` + +User request: + +$ARGUMENTS + +Instructions: + +- Use the `copilot-prompt-engineering` skill if available. +- Generate a self-contained prompt for the target AI. +- Include only context relevant to the request. +- Include Jira ID/title when the task maps to an active work item. +- Tell Copilot what to inspect before making assumptions. +- Include constraints, non-goals, expected output, and validation. +- If the user asks for implementation help but the write scope is unclear, generate an investigation/plan prompt rather than a code-change prompt. +- Do not mention this workspace unless explaining that the target AI will not have access to it. + +Return only the final prompt unless the user explicitly asks for commentary. diff --git a/.opencode/commands/fidelity-context.md b/.opencode/commands/fidelity-context.md index f8f7b1d..24e6dc2 100644 --- a/.opencode/commands/fidelity-context.md +++ b/.opencode/commands/fidelity-context.md @@ -16,6 +16,7 @@ Use these files as the baseline context: @ai/context/systems/index.md @ai/context/workstreams/index.md @ai/context/process/communication.md +@ai/context/process/ai-to-ai-prompting.md @ai/context/process/jira-story-rules.md @ai/context/people/manager.md @ai/context/people/index.md diff --git a/.opencode/plugins/fidelity-compaction.js b/.opencode/plugins/fidelity-compaction.js index 84a6668..216c162 100644 --- a/.opencode/plugins/fidelity-compaction.js +++ b/.opencode/plugins/fidelity-compaction.js @@ -22,6 +22,7 @@ export const FidelityCompaction = async ({ directory }) => { "ai/context/systems/index.md", "ai/context/workstreams/index.md", "ai/context/process/communication.md", + "ai/context/process/ai-to-ai-prompting.md", "ai/context/people/manager.md", "ai/context/people/index.md", "ai/work-items/index.md", diff --git a/.opencode/skills/copilot-prompt-engineering/SKILL.md b/.opencode/skills/copilot-prompt-engineering/SKILL.md new file mode 100644 index 0000000..8565da5 --- /dev/null +++ b/.opencode/skills/copilot-prompt-engineering/SKILL.md @@ -0,0 +1,43 @@ +--- +name: copilot-prompt-engineering +description: Create high-quality prompts for GitHub Copilot or another AI running on the Fidelity development machine, using this workspace's context without assuming the target AI has access to it. +compatibility: opencode +--- + +## When To Use + +Use this skill when the user wants a prompt for another AI assistant, GitHub Copilot, or the Fidelity development machine. + +## Workflow + +1. Identify the target task type: + - investigation + - implementation plan + - code change + - review + - test strategy + - story/PR drafting +2. Pull only the relevant context: + - `ai/work-items/` for ticket-specific context + - `ai/context/systems/` for component context + - `ai/context/workstreams/` for recurring constraints + - `ai/context/ios/` for Swift/iOS guidance +3. Make the prompt self-contained. +4. Tell the target AI what to inspect before acting. +5. State constraints, non-goals, and validation expectations. + +## Fidelity Prompting Rules + +- Include Jira ID and approved title when available. +- For REST work, say REST is behind a feature flag and GraphQL is fallback unless confirmed otherwise. +- For XFlow work, say behavior may depend on entry point, auth state, backend config, and consumer integration. +- For AO/Discourse issues, say external report vs regression must be separated. +- For SwiftUI/XFlow work, mention lifecycle, modal presentation, UIKit bridge, feature flag, and Fid4 validation if relevant. + +## Output Rules + +- Return only the prompt unless the user asks for explanation. +- Keep the prompt concise but complete. +- Prefer sections over paragraphs. +- Do not invent file paths unless the workspace context explicitly names them. +- If exact files are unknown, ask Copilot to locate them first. diff --git a/AGENTS.md b/AGENTS.md index 5d13de0..6229267 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ The detailed operating rules live in: - `ai/context/systems/index.md` - `ai/context/workstreams/index.md` - `ai/context/process/communication.md` +- `ai/context/process/ai-to-ai-prompting.md` - `ai/context/people/manager.md` - `ai/context/people/index.md` - `ai/work-items/index.md` @@ -57,6 +58,7 @@ These are also loaded through `opencode.json`. - Keep changes concise and auditable. - When the topic is architectural or historical, prefer updating the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` instead of overloading `ai/context/project.md`. - When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `ai/context/ios/` and the local OpenCode iOS skills before answering. +- When the user asks for a prompt for another AI, GitHub Copilot, or the Fidelity development machine, use `ai/context/process/ai-to-ai-prompting.md` and generate a self-contained prompt. - If a Swift/iOS recommendation depends on current Apple APIs, Xcode behavior, or framework migration guidance, verify against official Apple or Swift documentation before making strong claims. ## Communication diff --git a/README.md b/README.md index 795edef..ca3b66e 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ This repository is not the product codebase. It is the operational context layer - Keep Fidelity context current outside the main development machine - Turn fragmented daily work into reusable AI-ready context - Support standups, manager updates, Jira notes, and debugging summaries +- Generate high-quality prompts for GitHub Copilot or another AI on the Fidelity development machine - Improve communication quality without losing technical accuracy --- @@ -26,6 +27,7 @@ This workspace is used to: - preserve current project context between sessions - draft messages for the current manager or stakeholder with the right tone and scope - translate rough notes into concise native-sounding English +- generate self-contained prompts for another AI that does have access to the product codebase Core principle: @@ -165,6 +167,7 @@ Project commands live under `.opencode/commands/` and are intended to: - sync Mattermost context into the workspace inbox - draft standups - draft manager updates +- draft Copilot prompts for coding work on the Fidelity machine - convert rough notes into daily log updates This keeps AI output tied to the latest workspace state instead of relying on chat memory alone. diff --git a/ai/AGENTS.md b/ai/AGENTS.md index 7473d7f..c5faf5f 100644 --- a/ai/AGENTS.md +++ b/ai/AGENTS.md @@ -64,6 +64,7 @@ When drafting messages for a manager or stakeholder: - Before answering prompts about current work, verify `ai/state/current.md` and the latest relevant log in `ai/logs/` - Before answering architecture, process, or historical questions, check the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` - Before answering Swift, SwiftUI, iOS architecture, testing, or debugging questions, check `ai/context/ios/` and use the project-local iOS skills when available +- Before generating a prompt for another AI or GitHub Copilot, check `ai/context/process/ai-to-ai-prompting.md` and make the prompt self-contained - If `ai/inbox/mattermost-latest.md` exists, check it before answering prompts about current status, standups, or supervisor communication - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands - If a Mattermost sync or other context-ingestion step fails, do not update `ai/logs/`, `ai/state/`, or stable context files based on that failure @@ -80,6 +81,7 @@ When drafting messages for a manager or stakeholder: - Prefer updating stable project context over appending generic operational summaries - Do not create daily log entries for tooling activity, sync status, or generic chat noise - For Swift/iOS best-practice answers, distinguish current Apple guidance from project-safe recommendations when Fidelity constraints may change the answer +- For Copilot prompts, include only relevant context, tell Copilot what to inspect, and state constraints, non-goals, expected output, and validation - Do not ask the user what should be promoted after a successful sync unless multiple conflicting interpretations are equally plausible - When the user shares relevant new information, update today's log if the information belongs to the daily record - When the user corrects or changes stable context, update the canonical file directly: diff --git a/ai/context/process/ai-to-ai-prompting.md b/ai/context/process/ai-to-ai-prompting.md new file mode 100644 index 0000000..d47ac2b --- /dev/null +++ b/ai/context/process/ai-to-ai-prompting.md @@ -0,0 +1,69 @@ +# AI-To-AI Prompting + +## Goal + +Generate prompts that can be sent to another AI assistant on the Fidelity development machine, especially GitHub Copilot. + +--- + +## Operating Assumption + +This workspace does not contain the product codebase. The target AI has access to the Fidelity codebase on another machine. + +Therefore prompts must: + +- include only the relevant project context from this workspace +- tell the target AI what files/modules to inspect +- ask for a concrete output +- specify constraints and non-goals +- avoid pretending the target AI already has this workspace memory + +--- + +## Prompt Structure + +Use this structure by default: + +1. Role +2. Project context +3. Current task +4. Relevant ticket/context +5. Files/modules to inspect +6. Constraints +7. Expected output +8. Validation requirements + +--- + +## Prompt Quality Rules + +- Prefer precise task framing over long background dumps. +- Include Jira ID and title when the work maps to a ticket. +- Include current constraints such as REST feature flag, GraphQL fallback, auth state, backend-driven behavior, and consumer validation when relevant. +- Ask the target AI to inspect code before proposing changes. +- Ask for a plan first when the implementation scope is uncertain. +- Ask for code changes only when the desired write scope is clear. +- Include "Do not assume REST is active by default" for REST migration tasks. +- Include "Separate external issue from regression" for AO/Discourse issues. +- Include "Validate against Fid4/consumer path when needed" for XFlow integration tasks. + +--- + +## Bad Prompt Pattern + +"Fix this issue in XFlow." + +Why bad: + +- no entry point +- no auth state +- no expected behavior +- no ticket context +- no validation path +- no scope boundary + +--- + +## Good Prompt Pattern + +"You are working in the Fidelity iOS codebase. Inspect the XFlowSDK and XFlowViewMaker integration path for `PDIAP-14859 - Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation`. First identify where XFlow currently exposes SwiftUI through `UIHostingController`, where XFlowViewMaker consumes it, and what feature flag protects the migration path. Do not change code yet. Return a concise plan with affected files, risks, consumer validation needs in Fid4/FTTransfer, and any questions that block implementation." diff --git a/ai/context/process/index.md b/ai/context/process/index.md index ca6bfb9..76b75bf 100644 --- a/ai/context/process/index.md +++ b/ai/context/process/index.md @@ -5,6 +5,9 @@ - [communication.md](./communication.md) How to frame technical updates and external communication. +- [ai-to-ai-prompting.md](./ai-to-ai-prompting.md) + How to generate prompts for GitHub Copilot or another AI on the Fidelity development machine. + - [jira-story-rules.md](./jira-story-rules.md) How to create or reference stories with the right scope and precision. diff --git a/opencode.json b/opencode.json index cc73a79..af8dfc7 100644 --- a/opencode.json +++ b/opencode.json @@ -49,6 +49,7 @@ "./ai/context/systems/index.md", "./ai/context/workstreams/index.md", "./ai/context/process/communication.md", + "./ai/context/process/ai-to-ai-prompting.md", "./ai/context/process/jira-story-rules.md", "./ai/context/people/manager.md", "./ai/context/people/index.md", diff --git a/prompts/copilot-prompt.md b/prompts/copilot-prompt.md new file mode 100644 index 0000000..e7104b9 --- /dev/null +++ b/prompts/copilot-prompt.md @@ -0,0 +1,43 @@ +# Copilot Prompt Template + +Generate a prompt to send to GitHub Copilot on the Fidelity development machine. + +The prompt should be self-contained because Copilot will not have this workspace's memory unless the prompt includes it. + +Requirements: + +- Use precise senior-engineer language +- Include only relevant context +- Include Jira ID and approved title when available +- Tell Copilot what to inspect before changing code +- Make constraints explicit +- Specify whether the desired result is: + - investigation + - implementation plan + - code change + - review + - test strategy + - PR/story text +- Include expected output format +- Include validation requirements +- Avoid overloading the prompt with unrelated workspace history + +Default output format: + +```text +Role: + +Project context: + +Task: + +Relevant ticket/context: + +Inspect: + +Constraints: + +Expected output: + +Validation: +```