Milestone Overview
GospeLib development is organized into 30 milestones (M00--M29) spanning foundation infrastructure through mobile delivery. Milestones M00--M14 follow the original sprint-based timeline; M15+ were added during the A1 amendment and later planning phases with dates TBD. Each milestone has a dedicated detail page linked below.
Milestone Summary
| Milestone | Name | Status | Description |
|---|---|---|---|
| M00 | Tech Prep | Complete | Dev environment, toolchain, monorepo scaffold |
| M01 | Data Pipeline | Complete | Ingest CLI, corpus validation, test suite |
| M02 | Content API | Complete | Content service, gateway, shared types and SDK |
| M03 | Scripture Reader | Complete | Reader core, UI foundation, interaction layer |
| M04 | Annotations | Complete | Auth integration, annotations and study tools |
| M05 | Search & Staging | Complete | Full-text search, footnotes and cross-references |
| M06 | Interlinear & Lexicon | 22% | Hebrew/Greek interlinear display, lexicon UI |
| M07 | JST Interlinear | 40% | JST variant alignment and interlinear view |
| M08 | Knowledge Graph | 25% | Graph-based entity and relationship explorer |
| M09 | AI Study Assistant | Complete | LLM-powered study assistant integration |
| M10 | Monetization | Complete | Billing, subscriptions, Come Follow Me, sharing |
| M11 | Launch Readiness | Complete | Onboarding, polish, production infra, legal |
| M12 | Documentation Site | Complete | Docusaurus scaffold, API reference, blog |
| M13 | Multi-Translation & Schema Evolution | Complete | Schema fixes, translation support, enrichment |
| M14 | Corpus Harmonization | Complete | Cross-corpus alignment and normalization |
| M15 | A1 Cleanup & Data Foundation | 93% | Contradiction removal, data and label alignment |
| M16 | GUI Infrastructure & Layout | 87% | Plugin architecture, application shell restructure |
| M17 | Core UX | 91% | Hover cards, toolbars, Pinboard |
| M18 | Navigation Surfaces | Complete | Navigation components, command palette and history |
| M19 | Integration & Polish | Complete | Feature integration, accessibility and motion |
| M20 | Pipeline & Schema Alignment | Complete | Pipeline completion, package and schema alignment |
| M21 | Performance, Testing & Mobile | Complete | Performance, testing infrastructure, mobile adaptation |
| M22 | Session Advanced Features | Complete | Advanced session management capabilities |
| M23 | Study Map -- Core | 89% | Study map visualization and core navigation |
| M24 | Study Map -- Integration & Tools | Complete | Study map tool integration and workflows |
| M25 | Advanced Study Plugins | 80% | Scholarly and advanced study plugin suite |
| M26 | Plugin Ecosystem | Complete | Plugin registry, distribution, third-party support |
| M27 | Desktop Application | 0% | Electron/Tauri desktop packaging |
| M28 | Mobile Foundation | 13% | Expo/React Native foundation and shell |
| M29 | Mobile Features | 0% | Mobile-specific features and offline support |
Project Timeline
Project Start: Monday, March 9, 2026 (Week 1) Sprint Cadence: 2-week sprints
Note (2026-06-08): The original March 2026 timeline below is outdated. Actual completion dates for finished milestones are recorded in the milestone issue frontmatter (
completed:field). Sprint references (S0--S18) and due dates for M00--M13 are historical and no longer tracked.
ZenHub Configuration Reference
ZenHub Registry
All ZenHub entity IDs and configurations for MCP automation. IDs are opaque base64 strings resolved at runtime -- included here for reference and automation scripts.
Workspace & Repository
| Entity | Name | Zenhub ID |
|---|---|---|
| Organization | GospeLib | Z2lkOi8vcmFwdG9yL1plbmh1Yk9yZ2FuaXphdGlvbi8xNjU4MzY |
| Zenhub Workspace | GospeLib Web App MVP | Z2lkOi8vcmFwdG9yL1JlcG9zaXRvcnkvMTM0NzU4NjMx |
| GitHub Repository | GospeLib/main | Z2lkOi8vcmFwdG9yL1JlcG9zaXRvcnkvMTM0NzU4NjMy |
Issue Type Hierarchy
Zenhub enforces a 5-level hierarchy. Parent-child relationships must respect level ordering (L1 -> L2 -> L3 -> L4 -> L5).
| Level | Type | Zenhub ID | Used For |
|---|---|---|---|
| L1 | Initiative | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3NzQ | Top-level product initiative (GospeLib MVP) |
| L2 | Project | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3NzU | Phase groupings (Foundation, Reader, etc.) |
| L3 | Epic | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3NzY | Feature areas within milestones (25 epics) |
| L4 | Feature | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3ODM | New capabilities, user-facing functionality |
| L4 | Task | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3ODE | Chores, infrastructure, tests, docs |
| L4 | Bug | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3ODI | Defects, regressions |
| L5 | Sub-task | Z2lkOi8vcmFwdG9yL0lzc3VlVHlwZS8zODU3ODA | Decomposed work items under L4 issues |
Pipelines
| Pipeline | Zenhub ID | Description |
|---|---|---|
| New Issues | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNDU | Triage queue -- review and estimate before backlog |
| Icebox | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNDY | Low priority, not near-term |
| Product Backlog | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNDc | Reviewed, estimated, prioritized top-to-bottom |
| Sprint Backlog | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNDg | Ready for the current sprint, prioritized |
| In Progress | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNDk | Actively being worked on |
| Review/QA | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNTA | Code complete, pending review/testing |
| Done | Z2lkOi8vcmFwdG9yL1BpcGVsaW5lLzM1NDUxNTE | Tested and ready to deploy |
Sprints
2-week cadence. Sprint identifiers (S0--S18) map to Zenhub sprint entities.
| Sprint | Dates | Zenhub Name | Zenhub ID | Milestones |
|---|---|---|---|---|
| S0 | Mar 9--22 | Sprint: Mar 8 - Mar 22, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODIz | M00, M12 |
| S1 | Mar 23 -- Apr 5 | Sprint: Mar 22 - Apr 5, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI0 | M01 |
| S2 | Apr 6--19 | Sprint: Apr 5 - Apr 19, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI1 | M01, M13 |
| S3 | Apr 20 -- May 3 | Sprint: Apr 19 - May 3, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI2 | M01, M02, M13 |
| S4 | May 4--17 | Sprint: May 3 - May 17, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI3 | M02, M03, M13 |
| S5 | May 18--31 | Sprint: May 17 - May 31, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI4 | M03, M13 |
| S6 | Jun 1--14 | Sprint: May 31 - Jun 14, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODI5 | M03, M04 |
| S7 | Jun 15--28 | Sprint: Jun 14 - Jun 28, 2026 | Z2lkOi8vcmFwdG9yL1NwcmludC80NzQyODMw | M04 |
| S8 | Jun 29 -- Jul 12 | -- | Create | M05, M06, M13 |
| S9 | Jul 13--26 | -- | Create | M05, M06, M13 |
| S10 | Jul 27 -- Aug 9 | -- | Create | M06, M13 |
| S11 | Aug 10--23 | -- | Create | M06, M07 |
| S12 | Aug 24 -- Sep 6 | -- | Create | M07, M08, M13 |
| S13 | Sep 7--20 | -- | Create | M08, M09 |
| S14 | Sep 21 -- Oct 4 | -- | Create | M08, M09, M10 |
| S15 | Oct 5--18 | -- | Create | M08, M09, M10 |
| S16 | Oct 19 -- Nov 1 | -- | Create | M10, M11 |
| S17 | Nov 2--15 | -- | Create | M11 |
| S18 | Nov 16--29 | -- | Create | M11 |
Milestones
GitHub milestones set on the repository. Each maps 1:1 to a milestone markdown file.
| Milestone | Due Date | File |
|---|---|---|
| M00: Tech Prep | 2026-03-22 | docs/milestones/M00-tech-prep.md |
| M01: Data Pipeline | 2026-05-03 | docs/milestones/M01-data-pipeline.md |
| M02: Content API | 2026-05-17 | docs/milestones/M02-content-api.md |
| M03: Scripture Reader | 2026-06-14 | docs/milestones/M03-scripture-reader.md |
| M04: Annotations | 2026-07-05 | docs/milestones/M04-annotations.md |
| M05: Search & Staging | 2026-07-26 | docs/milestones/M05-search-staging.md |
| M06: Interlinear & Lexicon | 2026-08-23 | docs/milestones/M06-interlinear-lexicon.md |
| M07: JST Interlinear | 2026-09-13 | docs/milestones/M07-jst-interlinear.md |
| M08: Knowledge Graph | 2026-10-18 | docs/milestones/M08-knowledge-graph.md |
| M09: AI Study Assistant | 2026-10-18 | docs/milestones/M09-ai-study-assistant.md |
| M10: Monetization | 2026-11-01 | docs/milestones/M10-monetization.md |
| M11: Launch Readiness | 2026-11-29 | docs/milestones/M11-launch-readiness.md |
| M12: Documentation Site | 2026-03-22 | docs/milestones/M12-documentation-site.md |
| M13: Multi-Translation & Schema Evolution | 2026-09-06 | docs/milestones/M13-multi-translation-schema.md |
| M14: Corpus Harmonization | 2026-06-14 | docs/milestones/M14-corpus-harmonization.md |
| M15: A1 Cleanup & Data Foundation | TBD | docs/milestones/M15-a1-cleanup-data.md |
| M16: GUI Infrastructure & Layout | TBD | docs/milestones/M16-gui-infrastructure.md |
| M17: Core UX | TBD | docs/milestones/M17-core-ux.md |
| M18: Navigation Surfaces | TBD | docs/milestones/M18-navigation-surfaces.md |
| M19: Integration & Polish | TBD | docs/milestones/M19-integration-polish.md |
| M20: Pipeline & Schema Alignment | TBD | docs/milestones/M20-pipeline-schema.md |
| M21: Performance, Testing & Mobile | TBD | docs/milestones/M21-performance-mobile.md |
| M22: Session Advanced Features | TBD | docs/milestones/M22-session-advanced.md |
| M23: Study Map -- Core | TBD | docs/milestones/M23-study-map-core.md |
| M24: Study Map -- Integration & Tools | TBD | docs/milestones/M24-study-map-integration.md |
| M25: Advanced Study Plugins | TBD | docs/milestones/M25-advanced-plugins.md |
| M26: Plugin Ecosystem | TBD | docs/milestones/M26-plugin-ecosystem.md |
| M27: Desktop Application | TBD | docs/milestones/M27-desktop.md |
| M28: Mobile Foundation | TBD | docs/milestones/M28-mobile-foundation.md |
| M29: Mobile Features | TBD | docs/milestones/M29-mobile-features.md |
Labels
All GitHub labels to create on the repository. No other labels should exist.
| Label | Color | Category | Description |
|---|---|---|---|
Gateway | #2C5F8A | Service | Go API gateway service |
Content | #2C5F8A | Service | Python scripture graph queries |
Auth | #2C5F8A | Service | Go auth/Clerk wrapper |
Billing | #2C5F8A | Service | Go Stripe subscriptions |
AI | #2C5F8A | Service | Python LLM study assistant |
Notifications | #2C5F8A | Service | Go push/email notifications |
Ingest | #2C5F8A | Service | Python CLI data pipeline |
Web | #3D6B4F | App | Next.js web app |
Mobile | #3D6B4F | App | Expo/React Native mobile app |
Admin | #3D6B4F | App | Next.js admin dashboard |
UI | #7B68EE | Package | @gospelib/ui component library |
SDK | #7B68EE | Package | @gospelib/sdk client SDK |
Types | #7B68EE | Package | @gospelib/types shared types |
Config | #7B68EE | Package | @gospelib/config env schemas |
Testing | #7B68EE | Package | @gospelib/testing test helpers |
Go | #D2691E | Language | Go source code |
Python | #D2691E | Language | Python source code |
TypeScript | #D2691E | Language | TypeScript/React source code |
Infrastructure | #808080 | Scope | Docker, Terraform, K8s, CI/CD infra |
CI/CD | #808080 | Scope | GitHub Actions, pipelines, deployment |
Documentation | #808080 | Scope | Docs, ADRs, specs, guides |
Projects (L2)
Zenhub Projects group epics by development phase. Each Project is an L2 issue type that parents multiple L3 Epics.
| Project | Phase | Milestones | Start Date | End Date | Epics |
|---|---|---|---|---|---|
| Foundation | P0 | M00--M02, M13 | 2026-03-09 | 2026-05-17 | Tech Prep Foundation, Ingest Core Pipeline, Ingest Test Suite, Corpus Validation, Content Service API, Gateway Core, Shared Types & SDK, Schema Foundation & Critical Fixes, Content Service Translation Support |
| Reader | P1 | M03--M05 | 2026-05-04 | 2026-07-26 | Scripture Reader Core, UI Foundation, Reader Interaction, Auth Integration, Annotations & Study Tools, Full-Text Search, Footnotes & Cross-References |
| Enhancement | P2 | M06--M09, M13 | 2026-07-13 | 2026-10-18 | Interlinear & Lexicon, JST Interlinear, Knowledge Graph, AI Study Assistant, Word Alignment & Lexicon Enrichment, Citation Extraction |
| Launch | P3 | M10--M12 | 2026-09-21 | 2026-11-29 | Billing & Subscriptions, Come Follow Me, Social Sharing, User Onboarding, UI Polish & Performance, Production Infrastructure, Legal & Compliance, Docusaurus Scaffold & Content Migration, API Reference & Search, Blog & Deployment |
Epics (L3)
Each Epic is an L3 issue type parenting the L4 issues within its scope. Dates are derived from the sprint range of their child issues.
| Epic | Milestone | Parent Project | Start Date | End Date | Issues |
|---|---|---|---|---|---|
| Tech Prep Foundation | M00 | Foundation | 2026-03-09 | 2026-03-22 | 13 |
| Ingest Core Pipeline | M01 | Foundation | 2026-03-23 | 2026-05-03 | 13 |
| Ingest Test Suite | M01 | Foundation | 2026-04-20 | 2026-05-03 | 3 |
| Corpus Validation | M01 | Foundation | 2026-04-20 | 2026-05-03 | 6 |
| Content Service API | M02 | Foundation | 2026-04-20 | 2026-05-17 | 7 |
| Gateway Core | M02 | Foundation | 2026-05-04 | 2026-05-17 | 3 |
| Shared Types & SDK | M02 | Foundation | 2026-04-20 | 2026-05-17 | 9 |
| Scripture Reader Core | M03 | Reader | 2026-05-04 | 2026-06-14 | 8 |
| UI Foundation | M03 | Reader | 2026-05-04 | 2026-06-14 | 8 |
| Reader Interaction | M03 | Reader | 2026-06-01 | 2026-06-14 | 6 |
| Auth Integration | M04 | Reader | 2026-06-01 | 2026-06-28 | 3 |
| Annotations & Study Tools | M04 | Reader | 2026-06-15 | 2026-07-05 | 7 |
| Full-Text Search | M05 | Reader | 2026-06-29 | 2026-07-26 | 9 |
| Footnotes & Cross-References | M05 | Reader | 2026-06-29 | 2026-07-26 | 4 |
| Interlinear & Lexicon | M06 | Enhancement | 2026-06-29 | 2026-08-23 | 9 |
| JST Interlinear | M07 | Enhancement | 2026-08-10 | 2026-09-06 | 5 |
| Knowledge Graph | M08 | Enhancement | 2026-08-24 | 2026-10-18 | 8 |
| AI Study Assistant | M09 | Enhancement | 2026-09-07 | 2026-10-18 | 9 |
| Billing & Subscriptions | M10 | Launch | 2026-09-21 | 2026-11-01 | 7 |
| Come Follow Me | M10 | Launch | 2026-10-05 | 2026-11-01 | 3 |
| Social Sharing | M10 | Launch | 2026-10-19 | 2026-11-01 | 2 |
| User Onboarding | M11 | Launch | 2026-10-19 | 2026-11-01 | 3 |
| UI Polish & Performance | M11 | Launch | 2026-10-19 | 2026-11-15 | 3 |
| Production Infrastructure | M11 | Launch | 2026-11-02 | 2026-11-29 | 4 |
| Legal & Compliance | M11 | Launch | 2026-11-16 | 2026-11-29 | 2 |
| Docusaurus Scaffold & Content Migration | M12 | Launch | 2026-03-09 | 2026-03-22 | 12 |
| API Reference & Search | M12 | Launch | 2026-03-09 | 2026-03-22 | 4 |
| Blog & Deployment | M12 | Launch | 2026-03-09 | 2026-03-22 | 5 |
| Schema Foundation & Critical Fixes | M13 | Foundation | 2026-04-06 | 2026-05-03 | 12 |
| Content Service Translation Support | M13 | Foundation | 2026-05-04 | 2026-05-31 | 6 |
| Word Alignment & Lexicon Enrichment | M13 | Enhancement | 2026-06-29 | 2026-08-09 | 4 |
| Citation Extraction | M13 | Enhancement | 2026-08-24 | 2026-09-06 | 4 |
| A1 Contradiction Removal | M15 | A1 Amendment | TBD | TBD | 8 |
| Data Foundation & Label Alignment | M15 | A1 Amendment | TBD | TBD | 7 |
| Plugin & Composition Architecture | M16 | A1 Amendment | TBD | TBD | 9 |
| Application Shell Restructure | M16 | A1 Amendment | TBD | TBD | 5 |
| Hover Card System | M17 | A1 Amendment | TBD | TBD | 4 |
| Toolbar System | M17 | A1 Amendment | TBD | TBD | 2 |
| Pinboard & Comparison | M17 | A1 Amendment | TBD | TBD | 5 |
| Navigation Surfaces | M18 | A1 Amendment | TBD | TBD | 6 |
| Command Palette & History | M18 | A1 Amendment | TBD | TBD | 3 |
| Feature Integration | M19 | A1 Amendment | TBD | TBD | 9 |
| Accessibility & Motion | M19 | A1 Amendment | TBD | TBD | 4 |
| Pipeline Completion | M20 | A1 Amendment | TBD | TBD | 8 |
| Package & Schema Alignment | M20 | A1 Amendment | TBD | TBD | 4 |
| Performance & Testing | M21 | A1 Amendment | TBD | TBD | 5 |
| Mobile Adaptation | M21 | A1 Amendment | TBD | TBD | 3 |
| Session Advanced Features | M22 | A1 Amendment | TBD | TBD | 3 |
| Study Map Core | M23 | Study Map | TBD | TBD | 9 |
| Study Map Integration & Tools | M24 | Study Map | TBD | TBD | 7 |
| Advanced Study Plugins | M25 | Scholarly | TBD | TBD | 5 |
| Plugin Ecosystem | M26 | Plugins | TBD | TBD | 8 |
| Desktop Application | M27 | Desktop | TBD | TBD | 3 |
| Mobile Foundation | M28 | Mobile | TBD | TBD | 4 |
| Mobile Features | M29 | Mobile | TBD | TBD | 5 |
Initiative (L1)
| Initiative | Description | Projects |
|---|---|---|
| GospeLib MVP | Scripture study platform -- full-text, graph-based, AI-powered access to LDS canon + scholarly resources | Foundation, Reader, Enhancement, Launch |
Team
| Member | GitHub Login | Zenhub ID |
|---|---|---|
| Lance Miller | lellimecnar | Z2lkOi8vcmFwdG9yL1plbmh1YlVzZXIvNjczNTY0 |
Priority Scale
Zenhub's native priority field. Set via updateIssue.
| Priority | Code | Description |
|---|---|---|
| Critical | P0 | Absolute blocker -- milestone cannot ship without this |
| High | P1 | Important -- expected to ship within the milestone |
| Medium | P2 | Nice to have -- may defer if time is short |
| Low | P3 | Post-MVP or stretch goal |
Estimate Scale
Story points set via setIssueEstimate. Fibonacci-adjacent scale.
| Points | Relative Size | Examples |
|---|---|---|
| 1 | Trivial | Config change, typo fix |
| 2 | Small | Simple chore, scaffolding |
| 3 | Medium-small | Single-service utility, test suite |
| 5 | Medium | Standard feature, API endpoint |
| 8 | Large | Complex feature, multi-service |
| 13 | Extra-large | Major subsystem, critical path |
Enhancement Rules (Issue Metadata Conventions)
1. Label System
Labels are only for metadata that Zenhub does not handle natively. The following are managed by Zenhub and must never appear as labels:
- Issue Type ->
setIssueType - Priority -> native Zenhub priority field
- Milestone -> GitHub milestones
- Epic membership ->
setParentForIssues - Estimate ->
setIssueEstimate - Sprint ->
addIssuesToSprints - Pipeline ->
moveIssueToPipeline - Dependencies ->
createBlockage
The full label list with colors is in the ZenHub Registry > Labels section above. In particular, no type:*, priority:*, epic:*, service:*, or lang:* labels -- only clean, readable names.
2. Epic & Project Hierarchy
Epics use clean, human-readable titles -- not label-style epic:name slugs. The complete list of all epics, their parent projects, milestones, and date ranges is in the ZenHub Registry > Epics (L3) section above.
The full hierarchy is: Initiative (L1) -> Project (L2) -> Epic (L3) -> Feature/Task/Bug (L4) -> Sub-task (L5). Parent-child relationships are managed via setParentForIssues. Issue types are set via setIssueType using the IDs in the ZenHub Registry > Issue Type Hierarchy table.
3. Issue Type Mapping
All issue types are managed via the native Zenhub Issue Type field (setIssueType), not labels. See ZenHub Registry > Issue Type Hierarchy for IDs.
| Old Label | Zenhub Issue Type |
|---|---|
type:feature | Feature |
type:chore | Task |
type:infra | Task |
type:test | Task |
type:docs | Task |
type:design | Feature |
type:bug | Bug |
Sub-task is also available for use in Sub-Issues tables (see section 7).
4. Milestone-Level ZenHub Config
Each milestone file begins with a ZenHub Configuration table after the header and Phase Context section:
## ZenHub Configuration
| Field | Value |
| -------------------- | -------------------- |
| **Milestone** | M00: Tech Prep |
| **Due Date** | 2026-03-22 |
| **Default Pipeline** | Product Backlog |
| **Primary Epic(s)** | Tech Prep Foundation |
Fields map directly to Zenhub/GitHub native features. Release info, if needed, belongs in the Phase Context prose -- not in this table.
5. Issue Metadata Format
Each issue uses a compact metadata table containing only fields that map to MCP tool calls:
#### M00-001. Dev Environment Validation
| Field | Value |
| ------------ | ---------------------------- |
| **Type** | Task |
| **Epic** | Tech Prep Foundation |
| **Priority** | P0: Critical |
| **Estimate** | 3 |
| **Sprint** | S0 |
| **Pipeline** | Product Backlog |
| **Labels** | `Go`, `Python`, `TypeScript` |
Rules:
- Type -- one of: Feature, Task, Bug, Sub-task (maps to
setIssueType) - Epic -- the clean epic title (maps to
setParentForIssues) - Priority --
P0: Critical,P1: High,P2: Medium,P3: Low(maps to native Zenhub priority) - Estimate -- integer story points (maps to
setIssueEstimate) - Sprint -- sprint identifier e.g.
S0,S1--S2(maps toaddIssuesToSprints) - Pipeline --
Product Backlog,Sprint Backlog,In Progress, etc. (maps tomoveIssueToPipeline) - Labels -- only service/app/package/language/scope labels from section 1 (maps to
createGitHubIssuelabelsparam)
Omitted fields (inherited or not applicable):
- Milestone -- inherited from the file; set via GitHub milestone
- Assignee -- assigned at sprint planning, not in spec
- Dates -- set on Epics/Projects, not individual issues
6. Dependencies
Dependencies map directly to createBlockage(blockedIssueId, blockingIssueId) MCP calls.
Compact format (preferred when context is obvious):
##### Dependencies
| Blocked By | Blocks |
| ---------- | ------------------------- |
| -- | M00-002, M00-003, M00-004 |
Detailed format (when relationships need explanation):
##### Dependencies
| Relationship | Issue | Title |
| ------------ | ------- | -------------------------- |
| Blocked by | M00-001 | Dev Environment Validation |
| Blocks | M00-003 | Initial PostgreSQL Schemas |
If there are no dependencies:
##### Dependencies
None.
Milestone-Level Dependency Graph
Each milestone includes an ASCII dependency graph visualizing blocking relationships:
M##-001 --> M##-002 --> M##-003
\--> M##-004
M##-005 --> M##-006
M##-007 (independent)
Legend: A --> B means A blocks B (B is blocked by A)
7. Sub-Issues
Sub-issues use the Sub-task issue type and are linked via setParentForIssues.
##### Sub-Issues
| ID | Title | Type | Estimate | Labels |
| --------- | --------------- | -------- | -------- | ------------------- |
| M00-001-a | Sub-issue title | Sub-task | 2 | `Content`, `Python` |
Sub-issues inherit their parent's Epic, Milestone, and Sprint -- these fields are omitted from the sub-issue table.
Convert a subtask to a sub-issue when it is:
- Independently estimable (could be assigned story points)
- Independently assignable (different person could do it)
- Independently testable (has its own acceptance criteria)
- Substantial (more than a checkbox-level task, typically 2+ story points)
Keep lightweight items as Subtasks (checkbox list within the issue body).
8. MCP Translation Reference
Every issue metadata field maps to a specific MCP tool call. This table is the agent's translation guide:
| Issue Field | MCP Tool | Parameters |
|---|---|---|
| Title | createGitHubIssue | title |
| Description + AC + Notes | createGitHubIssue | body (markdown) |
| Type | setIssueType | issueIds, issueTypeId |
| Epic (parent) | setParentForIssues | parentIssueId, childIssueIds |
| Estimate | setIssueEstimate | issueId, estimate |
| Sprint | addIssuesToSprints | issueIds, sprintIds |
| Pipeline | moveIssueToPipeline | issueId, pipelineId |
| Labels | createGitHubIssue | labels (array, on create) |
| Dependencies | createBlockage | blockedIssueId, blockingIssueId |
| Sub-Issues | setParentForIssues | parentIssueId, childIssueIds |
| Dates (Epics only) | setDatesForIssue | issueId, startDate, endDate |
| Assignees | assignIssues | issueIds, assigneeIds |
| Priority | updateIssue | issueId (via native priority field) |
Notes:
issueTypeId,pipelineId,sprintIdare runtime-resolved viagetIssueTypes,getWorkspacePipelinesAndRepositories,getSprint/listRecentSprintsrepositoryIdis resolved viagetWorkspacePipelinesAndRepositories- Epic IDs are resolved by searching for the epic title after creation
- Labels are passed as string arrays matching the names defined in section 1
9. Sections to Preserve Unchanged
The following sections within each milestone file must not be modified during enhancement:
- Phase Context
- Prerequisites table
- Epic / Story Areas table
- Document References
- Sprint Mapping
- Relevant Risks
- Cross-Cutting Concerns (Testing, Documentation, CI/CD)
- All Description text
- All Acceptance Criteria
- All Technical Notes
10. Summary Statistics
Each milestone ends with a summary table:
## Summary
| Metric | Count |
| ------------------------- | ------ |
| Total Issues | N |
| Sub-Issues | N |
| Total Estimate (pts) | N |
| Sprints | S#--S# |
| Dependencies (blocking) | N |
| Dependencies (blocked by) | N |