APEX Delivery Pipeline for Copilot

APEX Delivery Pipeline is a Copilot-first VS Code extension for teams that want AI-assisted delivery work to stay in the repository instead of being scattered across chat tabs, scratch files, and ad hoc checklists. It combines file-based epics, workflow-aware phase execution, direct model runs, scoped GitHub Copilot Chat handoff, branch-to-epic coordination, linked Git worktrees, PR review artifacts, MCP configuration, spec-kit workspaces, and Copilot bootstrap assets in one editor workflow.

This project is optimized for VS Code plus GitHub Copilot Chat. It keeps repo-native artifacts, .github/ Copilot assets, and workspace-local .vscode/mcp.json in one Copilot-oriented workflow.

Why This Project Exists

• Keep delivery state in the repo: epics, phase artifacts, status files, workflow snapshots, and developer traces live beside the code.
• Run the active phase with Copilot from the APEX tree instead of rebuilding prompt context by hand.
• Apply workflow defaults, phase overrides, and role policies without hand-editing large JSON payloads.
• Attach build, test, and lint evidence to the current artifact when verification commands are available.
• Keep branch coordination and PR review history tied to the same epic through explicit branch bindings, linked worktrees, and generated review artifacts.
• Bootstrap specs/<feature>/, .github/ Copilot assets, and .vscode/mcp.json from the same extension.

Core Capabilities

• Activity Bar delivery pipeline for repo-local epics.
• Sample epic creation under docs/ai-delivery/epics/<KEY>/.
• Workflow-scoped phase definitions with custom templates, file-backed prompt sources, and per-phase session defaults.
• Run Phase with Copilot through direct language model execution when available, with scoped chat fallback when it is not.
• Reopen the stored epic-scoped fallback chat session on rerun instead of creating a fresh ask-mode chat when the same epic already has prior fallback session state.
• Epic-scoped chat routing markers and trace records using APEX_SESSION=....
• Guided Autopilot commands for phase execution, fully automatic mode, pause, and resume.
• Workspace workflow editor for templateRef, outputRef, starterPromptRef, and ordered phase definitions.
• Guided phase profile editor for autoSubmit, agentTag, and preferredChatAgent.
• Direct artifact rewrite proposal flow with diff preview and explicit apply or reject.
• Git branch-to-epic linking, linked branch worktree opening, and repo-local PR review artifact generation.
• Developer Trace Panel with prompts, context files, execution path, fallback reason, role notes, and transport metadata.
• Spec Kit workspace scaffolding and Copilot bootstrap pack generation.
• MCP server configuration for Atlassian remote MCP or custom stdio servers.

Default Workflow

What The Extension Creates

Generated spec-kit workspace:

specs/<feature>/
  spec.md
  plan.md
  tasks.md
  research.md
  data-model.md
  contracts/README.md
  quickstart.md

Generated Copilot bootstrap pack:

.github/
  copilot-instructions.md
  prompts/apex-delivery.prompt.md
  prompts/apex-tdd-epic.prompt.md
  instructions/apex-delivery.instructions.md
  instructions/apex-tdd-micro-commit.instructions.md
  agents/apex-delivery-orchestrator.agent.md
  agents/apex-tdd-epic-executor.agent.md
  skills/apex-delivery/SKILL.md

The bootstrap pack is no-overwrite by default. Existing .github/ files are skipped so teams can merge generated assets deliberately.

Quick Start

1. Open this folder in VS Code.
2. Run npm install.
3. Run npm run compile.
4. Press F5 and select Run APEX Delivery Extension.
5. In the Extension Development Host, open the APEX Delivery view from the Activity Bar.
6. Run Start APEX Delivery if you want the extension to route you to the right entry point for a ticket, epic, or spec-only flow.
7. Run Create Epic if you want a ready-made repo-local workflow to explore.
8. Run Start Integrated Delivery Flow if you want both a spec-kit workspace and a Copilot bootstrap pack without creating an APEX epic.
9. Use Configure Workflows if you want custom phase order, custom templates, or file-backed prompt sources.
10. Use Configure MCP Server if the workflow needs Jira, Confluence, or a custom MCP endpoint.
11. On an active phase, run Run Phase with Copilot or start with Propose Artifact Update when you want a reviewable artifact diff.
12. Review the artifact, trace, and verification evidence, then run Mark Phase Passed or continue with guided execution.

Recommended Daily Flow

1. Create or open an epic under docs/ai-delivery/epics/<KEY>/.
2. Use Link Current Branch To Epic or Link Branch To Epic when implementation or review work should stay explicitly bound to that epic.
3. Use Open Linked Branch Worktree when you want the linked branch in a separate worktree or window.
4. Open the active artifact with Open or Create Artifact.
5. Run Run Phase with Copilot to use direct model execution or the scoped Copilot Chat handoff.
6. Use Propose Artifact Update when you want a reviewable diff instead of an immediate chat-driven rewrite.
7. Inspect Open Developer Trace Panel when you need the exact prompt, context set, execution path, or fallback reason.
8. Run Configure Phase Profile when a single phase needs different auto-submit, agent tag, or preferred-agent defaults.
9. Use Review Pull Request or Generate PR Review Artifact when review output should land back into the epic's repo-local artifacts.
10. Run Run Guided Autopilot or Run Fully Automatic Autopilot from the Command Palette when the current phase policy allows it.
11. Use Pause Guided Autopilot or Resume Guided Autopilot when the flow requires human review or a later continuation.
12. Run Mark Phase Passed when the current artifact satisfies the gate and should advance the workflow.

Command Surface

Configuration Model

The extension resolves run preferences in this order:

phaseProfiles -> workflow snapshot sessionDefaults -> rolePolicies -> workspace defaults

Key settings:

Representative workflow definition:

{
  "apexDelivery.workflowDefinitions": {
    "investigate-workflow": {
      "name": "Investigate Only",
      "phases": [
        {
          "id": "investigate",
          "name": "Investigate",
          "owner": "Business Analyst",
          "artifact": "DISCOVER.md",
          "templateRef": "docs/ai-delivery/templates/investigate-template.md",
          "gate": "Gate 1",
          "outputRef": "docs/ai-delivery/prompts/investigate-output.md",
          "sessionDefaults": {
            "autoSubmit": false,
            "agentTag": "#workflow-investigate",
            "preferredChatAgent": "Workflow Analyst",
            "starterPromptRef": "docs/ai-delivery/prompts/investigate-starter.md"
          },
          "autopilot": {
            "enabled": true,
            "retryLimit": 1,
            "pauseOnManualIntervention": true
          }
        }
      ]
    }
  }
}

Copilot Execution Model

Run Phase with Copilot can take multiple paths depending on what the environment exposes:

• Direct model path: the extension uses vscode.lm.selectChatModels() and sends a scoped request itself.
• Agent chat path: the extension opens GitHub Copilot Chat in agent mode with the relevant files attached.
• Scoped chat fallback: when direct execution is unavailable, the extension prepares a dedicated prompt for the current epic and opens GitHub Copilot Chat in ask mode.

Important behavior:

• The prepared prompt includes an APEX_SESSION=... marker so the same epic can keep a consistent conversation identity in trace and fallback flows.
• If a fallback chat session already exists for the same epic, rerunning the phase reopens that stored epic-scoped session instead of issuing a fresh ask-mode chat launch. When the public chat surface cannot prefill the reopened session deterministically, the scoped prompt is copied for manual continuation.
• preferredChatAgent is a best-effort hint in public GitHub Copilot Chat launches. The public chat-open commands do not guarantee hard agent locking.
• The optional @apex participant is still available for follow-up, but the primary handoff flow does not depend on it.

Guided Autopilot

Guided Autopilot is phase-scoped and only continues automatically when the workflow policy for the current phase enables it.

• agent-pause keeps the Copilot-agent-first behavior and pauses when the public chat surface no longer exposes enough completion state.
• fully-automatic skips chat paths and only continues when the extension can observe a direct model completion itself.
• Verification failure, retry-limit exhaustion, or unsaved manual edits still pause the flow.
• Pause and resume state is stored in workspace state so the epic can be continued later.

MCP Setup

Run Configure MCP Server from the Command Palette or the APEX view title.

Available modes:

The MCP updater is append-only for server names. It avoids overwriting an existing server entry with the same name.

Repository Layout

Development, Packaging, and Publishing

Available scripts:

Marketplace notes:

• Publisher id is currently vndkubi.
• Validate README, manifest metadata, and packaged contents before publish.
• Packaging and publishing SOP lives in docs/MARKETPLACE-PUBLISHING-SOP.md.

Relationship To Other Projects

This extension connects three adjacent layers:

• Repo-local delivery epics under docs/ai-delivery/epics/
• spec-kit workspaces under specs/<feature>/
• Copilot bootstrap assets under .github/

This project stays focused on GitHub Copilot Chat, workspace MCP configuration, and repository-visible delivery artifacts inside VS Code.

License

MIT