Feature: Spec-to-Delivery Workflow with Milestones, Acceptance Gates, and GitHub Linking

[hoangsonww]

Summary

Create a spec-to-delivery workflow that turns a structured feature spec into planned Forge tasks, acceptance gates, traceable implementation steps, GitHub issue/PR links, and completion evidence.

Problem / Opportunity

Forge already has a spec command surface, a planner/architect/executor/reviewer loop, validation gates, task persistence, events, memory, and Git tooling. Large features still require users to manually coordinate:

• Breaking a feature spec into milestones and tasks.
• Mapping acceptance criteria to validation commands and reviewer checks.
• Linking local Forge tasks to GitHub issues and pull requests.
• Preserving evidence that each acceptance criterion was satisfied.
• Resuming multi-session feature work without losing the original intent.

A spec-to-delivery workflow would make Forge more useful for substantial product work, not just single-prompt tasks.

Proposed Feature

Add an end-to-end feature delivery flow:

• Structured spec format with summary, goals, non-goals, constraints, milestones, acceptance criteria, validation gates, and rollout notes.
• forge spec plan <spec> to generate a milestone DAG and task set.
• forge spec run <spec> to execute approved tasks while preserving links back to spec sections.
• Acceptance gate tracking that records evidence from tests, lint/build/typecheck, reviewer output, and user confirmations.
• GitHub linking for issues/PRs when configured, without requiring GitHub for local-only use.
• Dashboard view for spec progress, blocked gates, and task evidence.

Scope

Expected implementation areas:

• src/cli/commands/spec.ts for spec parsing, planning, running, and status commands.
• src/core/spec.ts, src/core/orchestrator.ts, and src/core/loop.ts for milestone/task execution.
• src/scheduler/dag.ts for milestone dependency handling.
• src/persistence/tasks.ts, src/persistence/events.ts, and SQLite indexing for spec/task/gate records.
• src/tools/git.ts and optional GitHub/MCP integration for issue/PR linking.
• src/ui/server.ts and dashboard views for spec progress.
• Docs covering spec format, acceptance gates, and GitHub linking.

Acceptance Criteria

• Users can define or import a structured spec and validate it before execution.
• Forge can generate a milestone DAG with task-level acceptance criteria from a spec.
• Each generated task preserves links to the spec sections and acceptance gates it supports.
• Acceptance gates can be satisfied by configured validation commands, reviewer decisions, or explicit user confirmation.
• GitHub issue/PR links can be attached when configured, but local-only workflows remain fully supported.
• Dashboard shows spec progress by milestone, task state, blocked gate, and completion evidence.
• State transitions for generated tasks obey LEGAL_TRANSITIONS in src/persistence/tasks.ts.
• Tests cover spec parsing, DAG generation, gate persistence, local-only execution, and mocked GitHub linking.

Non-Goals

• Replacing external project management systems.
• Requiring GitHub for all spec workflows.
• Automatically merging pull requests or publishing releases.
• Treating vague free-form prompts as complete specs without validation.

Dependencies / Risks

• Spec workflows must not bypass plan approval, permission gates, or validation gates.
• GitHub integration should be optional and mocked in tests to avoid network calls.
• Gate evidence needs to be concise enough to review but detailed enough to audit.
• Long-running specs need resumability without corrupting task state.

Open Questions

• Should the initial spec format be Markdown with front matter, JSON/YAML, or both?
• Should spec-generated tasks be editable individually before execution?
• How should Forge handle acceptance criteria that cannot be verified automatically?
• Should GitHub links be managed through MCP, gh, or an internal adapter abstraction?