apex-accelerator: Instructions file for GitHub Copilot

Lesson Collection Protocol

Orchestrators collect process observations during workflow execution and generate 09-lessons-learned.json + 09-lessons-learned.md as workflow completion artifacts (same pattern as 00-handoff.md and 00-session-state.json).

Initialization

Session state follows the apex-recall rules in copilot-instructions.md (init for new projects, show on resume); never read or edit 00-session-state.json directly. On resume, preserve existing lesson entries. Initialize with apex-recall init <project> --json. Create 09-lessons-learned.json with file-editing tools only when absent:

{
  "workflow_mode": "production",
  "project": "{project}",
  "lessons": []
}

New workflow logs use "production". The schema's historical "e2e" value and existing lesson artifacts remain valid compatibility evidence; do not rewrite them or infer a runnable E2E workflow from that retained value.

The CLI has no apex-recall lessons subcommand. Append schema-compliant entries to the lesson artifact with file-editing tools; session findings are not a replacement for the structured lesson log. Register the artifact through recall:

apex-recall checkpoint <project> <step> lessons \
   --artifact agent-output/<project>/09-lessons-learned.json --json

When to Record a Lesson

Production Orchestrator Triggers

• Challenger review returns must_fix findings
• User rejects an artifact and requests revision (log what was wrong)
• Subagent returns NEEDS_REVISION verdict
• Deployment what-if reveals Azure Policy violations
• User explicitly flags an issue or concern during approval

Lesson Schema

Formal JSON Schema: tools/schemas/lesson-log.schema.json. Required fields per entry: id, step, category, severity, title, observation, root_cause, recommendation, applies_to, applies_to_paths, status. Allowed enums:

• category: agent-behavior, skill-gap, prompt-quality, validation-gap, workflow-design, context-budget, artifact-quality, factual-accuracy, deployment-failure
• severity: critical, high, medium, low
• status: open, in-progress, resolved, wont-fix