GSD + Agent-Project Template Integration

.planning/PROJECT.md

@@ -0,0 +1,75 @@
+# GSD + Agent-Project Template Integration
+
+## What This Is
+
+A unified agentic development framework that combines GSD's hierarchical planning and phase-based execution with the agent-project template's rigorous documentation standards, Mermaid diagram conventions, and "Everything is Code" project tracking. This integration creates a comprehensive system for managing complex projects from high-level vision through implementation and verification.
+
+## Core Value
+
+Developers can plan projects with GSD's structured phases while maintaining the template's superior documentation quality and agent-optimized workflow — getting both systematic planning and execution excellence in one cohesive system.
+
+## Requirements
+
+### Validated
+
+- ✓ AGENTS.md entrypoint system — existing
+- ✓ 14-step agent workflow with human checkpoints — existing
+- ✓ Mermaid diagram standards (23 types) — existing
+- ✓ Everything-is-code tracking (PRs/issues/kanban as files) — existing
+- ✓ CrewAI review system with memory — existing
+- ✓ Local CI runner (`./scripts/ci-local.sh`) — existing
+
+### Active
+
+- [ ] Integrate GSD `.planning/` hierarchy with existing project structure
+- [ ] Create unified workflow: GSD phases drive template execution
+- [ ] Align kanban boards with GSD phase tracking
+- [ ] Merge Mermaid standards into GSD documentation
+- [ ] Create ADRs for integration architecture decisions
+- [ ] Build comprehensive integration guide
+
+### Out of Scope
+
+- Replacing template's Mermaid standards with GSD's simpler versions — template standards are superior and will be preserved
+- Modifying CrewAI review system architecture — integration at orchestration layer only
+- Changing GitHub Actions workflows — focus is on local development experience
+- Supporting non-markdown project tracking — everything-is-code principle is non-negotiable
+
+## Context
+
+This project emerges from the recognition that GSD provides excellent high-level planning and phase orchestration, while the agent-project template provides superior documentation standards and agent workflow patterns. Rather than choosing one, we're integrating both to create a best-of-both-worlds solution.
+
+The agent-project template has invested heavily in:
+
+- Mermaid diagram accessibility and styling standards
+- Document templates for PRs, issues, kanban, ADRs
+- Idempotent script patterns for CI
+- Token management and context budget guides
+
+GSD provides:
+
+- Hierarchical project planning (PROJECT → REQUIREMENTS → ROADMAP)
+- Phase-based execution with parallel agent orchestration
+- Milestone management and audit workflows
+- Research agents for domain exploration
+
+## Constraints
+
+- **Tech Stack**: Must work with existing Node.js/pnpm ecosystem
+- **Compatibility**: Cannot break existing `./scripts/ci-local.sh` usage
+- **Documentation**: Must follow existing markdown and Mermaid style guides
+- **Git**: All planning artifacts committed (config.commit_docs: true)
+- **Timeline**: Single-session implementation on experimental branch
+
+## Key Decisions
+
+| Decision                            | Rationale                                                                                                       | Outcome   |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------- |
+| Use GSD as orchestrator             | GSD provides planning layer that template lacks; template provides execution layer that GSD delegates to agents | — Pending |
+| Preserve template Mermaid standards | Template has 23 diagram type guides vs GSD's minimal approach; quality advantage clear                          | — Pending |
+| Keep docs/project/ tracking         | Everything-is-code principle proven valuable; GSD's .planning/ complementary (planning vs execution tracking)   | — Pending |
+| YOLO mode for integration           | User explicitly wants "just get shit done"; checkpoints at phase boundaries sufficient                          | — Pending |
+
+---
+
+_Last updated: 2026-02-19 after initialization_

.planning/REQUIREMENTS.md

@@ -0,0 +1,107 @@
+# Requirements: GSD + Agent-Project Template Integration
+
+**Defined:** 2026-02-19
+**Core Value:** Unified planning and execution framework combining GSD's hierarchical planning with template's rigorous documentation and agent workflow
+
+## v1 Requirements
+
+Requirements for initial integration release. Each maps to roadmap phases.
+
+### Planning Layer Integration
+
+- [x] **PLAN-01**: GSD `.planning/` directory structure integrates cleanly with existing repo layout
+- [x] **PLAN-02**: PROJECT.md captures integration vision and preserves template's existing validated capabilities
+- [x] **PLAN-03**: REQUIREMENTS.md defines REQ-ID traceability aligned with template conventions
+- [x] **PLAN-04**: ROADMAP.md phases map to incremental integration milestones
+- [x] **PLAN-05**: STATE.md tracks project memory and decision history
+
+### Documentation Standards Alignment
+
+- [x] **DOC-01**: Template's Mermaid style guide (23 diagram types) takes precedence over GSD defaults
+- [x] **DOC-02**: Markdown style guide applies to all `.planning/` artifacts
+- [x] **DOC-03**: ADR format maintained for integration architecture decisions
+- [x] **DOC-04**: All diagrams follow accessibility standards (accTitle, accDescr, classDef)
+
+### Execution Layer Integration
+
+- [x] **EXEC-01**: GSD phases spawn template 14-step workflow agents
+- [x] **EXEC-02**: AGENTS.md remains canonical entrypoint for all agent work
+- [x] **EXEC-03**: Local CI runner (`./scripts/ci-local.sh`) validates phase deliverables
+- [x] **EXEC-04**: CrewAI review system processes phase outputs
+
+### Project Tracking Integration
+
+- [x] **TRACK-01**: Kanban boards reference active GSD phase and REQ-IDs
+- [x] **TRACK-02**: PR records document phase deliverables with traceability
+- [x] **TRACK-03**: Issue records track blockers and decisions (demonstrated)
+- [x] **TRACK-04**: Source-of-truth sync updates both `.planning/` and `docs/project/`
+
+### Verification and Guide
+
+- [x] **VERIFY-01**: Integration tested end-to-end on experimental branch
+- [x] **VERIFY-02**: Comprehensive integration guide created with examples
+- [x] **VERIFY-03**: All v1 requirements mapped to phases with success criteria
+- [x] **VERIFY-04**: ADR-009 documents architecture decision and consequences
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Automation
+
+- **AUTO-01**: `./scripts/ci-local.sh` validates GSD phase alignment
+- **AUTO-02**: Git hooks prevent commits that break planning/tracking sync
+- **AUTO-03**: Automated REQ-ID consistency checker
+
+### Template Enhancements
+
+- **TMPL-01**: Kanban template includes GSD phase reference section
+- **TMPL-02**: PR template includes REQ-ID traceability fields
+- **TMPL-03**: Issue template includes phase blocker tracking
+
+## Out of Scope
+
+| Feature                              | Reason                                                                              |
+| ------------------------------------ | ----------------------------------------------------------------------------------- |
+| Replacing template Mermaid standards | Template has 23 diagram type guides; GSD has minimal approach; template is superior |
+| Modifying CrewAI review architecture | Integration at orchestration layer only; review system remains unchanged            |
+| GitHub Actions workflow changes      | Focus is local development experience; CI/CD remains separate concern               |
+| Non-markdown project tracking        | Everything-is-code principle is non-negotiable; no external PM tools                |
+| GSD cloud/sync features              | Local-first approach maintained; no external dependencies                           |
+
+## Traceability
+
+| Requirement | Phase   | Status   |
+| ----------- | ------- | -------- |
+| PLAN-01     | Phase 1 | Complete |
+| PLAN-02     | Phase 1 | Complete |
+| PLAN-03     | Phase 1 | Complete |
+| PLAN-04     | Phase 1 | Complete |
+| PLAN-05     | Phase 1 | Complete |
+| DOC-01      | Phase 2 | Complete |
+| DOC-02      | Phase 2 | Complete |
+| DOC-03      | Phase 1 | Complete |
+| DOC-04      | Phase 2 | Complete |
+| EXEC-01     | Phase 2 | Complete |
+| EXEC-02     | Phase 2 | Complete |
+| EXEC-03     | Phase 3 | Complete |
+| EXEC-04     | Phase 3 | Complete |
+| TRACK-01    | Phase 2 | Complete |
+| TRACK-02    | Phase 2 | Complete |
+| TRACK-03    | Phase 2 | Complete |
+| TRACK-04    | Phase 3 | Complete |
+| VERIFY-01   | Phase 3 | Complete |
+| VERIFY-02   | Phase 3 | Complete |
+| VERIFY-03   | Phase 1 | Complete |
+| VERIFY-04   | Phase 1 | Complete |
+
+**Coverage:**
+
+- v1 requirements: 21 total
+- Mapped to phases: 21
+- Unmapped: 0 ✓
+
+---
+
+_Requirements defined: 2026-02-19_
+_Last updated: 2026-02-19 — All 21 v1 requirements complete_

.planning/ROADMAP.md

@@ -0,0 +1,150 @@
+# Roadmap: GSD + Agent-Project Template Integration
+
+**Project:** GSD + Agent-Project Template Integration  
+**Created:** 2026-02-19  
+**Phases:** 3  
+**Requirements:** 21 v1 requirements
+
+---
+
+## Overview
+
+| #   | Phase                               | Goal                                                | Requirements                               | Success Criteria           |
+| --- | ----------------------------------- | --------------------------------------------------- | ------------------------------------------ | -------------------------- |
+| 1   | Foundation & Planning               | Establish GSD structure and document architecture   | PLAN-01–05, DOC-03, VERIFY-04              | 7 requirements, 4 criteria |
+| 2   | Documentation & Execution Alignment | Align standards and connect execution layers        | DOC-01–02, DOC-04, EXEC-01–02, TRACK-01–03 | 9 requirements, 4 criteria |
+| 3   | Verification & Guide                | Validate integration and create comprehensive guide | EXEC-03–04, TRACK-04, VERIFY-01–03         | 5 requirements, 4 criteria |
+
+---
+
+## Phase 1: Foundation & Planning
+
+**Goal:** Establish GSD `.planning/` structure and document integration architecture decisions
+
+**Requirements:**
+
+- PLAN-01: GSD `.planning/` directory structure integrates cleanly
+- PLAN-02: PROJECT.md captures integration vision
+- PLAN-03: REQUIREMENTS.md defines REQ-ID traceability
+- PLAN-04: ROADMAP.md phases map to integration milestones
+- PLAN-05: STATE.md tracks project memory
+- DOC-03: ADR format maintained for integration decisions
+- VERIFY-04: ADR-009 documents architecture decision
+
+**Success Criteria:**
+
+1. `.planning/` directory created with all core files (PROJECT, REQUIREMENTS, ROADMAP, STATE, config)
+2. ADR-009 created in `agentic/adr/` documenting integration architecture
+3. All planning files follow template markdown style guide
+4. Config.json configured for YOLO mode with appropriate workflow settings
+
+**Deliverables:**
+
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+- `.planning/config.json`
+- `agentic/adr/ADR-009-gsd-integration-orchestration-layer.md`
+
+---
+
+## Phase 2: Documentation & Execution Alignment
+
+**Goal:** Align documentation standards and connect GSD orchestration with template execution
+
+**Requirements:**
+
+- DOC-01: Template Mermaid standards take precedence
+- DOC-02: Markdown style guide applies to planning artifacts
+- DOC-04: All diagrams follow accessibility standards
+- EXEC-01: GSD phases spawn template 14-step workflow
+- EXEC-02: AGENTS.md remains canonical entrypoint
+- TRACK-01: Kanban boards reference GSD phase
+- TRACK-02: PR records document phase deliverables
+- TRACK-03: Issue records track blockers
+
+**Success Criteria:**
+
+1. All `.planning/` markdown files pass template style guide validation
+2. Any diagrams in planning files use template Mermaid standards
+3. Kanban board updated with GSD phase reference
+4. Phase planning and execution flow documented
+
+**Deliverables:**
+
+- Updated kanban board with phase tracking
+- Phase 1 execution complete with SUMMARY.md
+- Integration patterns documented in guide draft
+
+---
+
+## Phase 3: Verification & Guide Creation
+
+**Goal:** Validate integration works end-to-end and create comprehensive user guide
+
+**Requirements:**
+
+- EXEC-03: Local CI runner validates phase deliverables
+- EXEC-04: CrewAI review system processes phase outputs
+- TRACK-04: Source-of-truth sync updates both systems
+- VERIFY-01: Integration tested end-to-end
+- VERIFY-02: Comprehensive integration guide created
+- VERIFY-03: All v1 requirements mapped to phases
+
+**Success Criteria:**
+
+1. `./scripts/ci-local.sh` passes on all changes
+2. All requirements traceable to phases and verification criteria
+3. Comprehensive integration guide created with examples
+4. Guide includes architecture diagram, workflow examples, and quick reference
+
+**Deliverables:**
+
+- `docs/project/GSD_INTEGRATION_GUIDE.md` — Comprehensive integration guide
+- `docs/project/pr/pr-NNNNNNNN-gsd-integration.md` — PR record for this work
+- All v1 requirements marked complete
+- STATE.md updated with final status
+
+---
+
+## Traceability Matrix
+
+| Requirement | Phase   | Status  |
+| ----------- | ------- | ------- |
+| PLAN-01     | Phase 1 | Pending |
+| PLAN-02     | Phase 1 | Pending |
+| PLAN-03     | Phase 1 | Pending |
+| PLAN-04     | Phase 1 | Pending |
+| PLAN-05     | Phase 1 | Pending |
+| DOC-03      | Phase 1 | Pending |
+| VERIFY-04   | Phase 1 | Pending |
+| DOC-01      | Phase 2 | Pending |
+| DOC-02      | Phase 2 | Pending |
+| DOC-04      | Phase 2 | Pending |
+| EXEC-01     | Phase 2 | Pending |
+| EXEC-02     | Phase 2 | Pending |
+| TRACK-01    | Phase 2 | Pending |
+| TRACK-02    | Phase 2 | Pending |
+| TRACK-03    | Phase 2 | Pending |
+| EXEC-03     | Phase 3 | Pending |
+| EXEC-04     | Phase 3 | Pending |
+| TRACK-04    | Phase 3 | Pending |
+| VERIFY-01   | Phase 3 | Pending |
+| VERIFY-02   | Phase 3 | Pending |
+| VERIFY-03   | Phase 3 | Pending |
+
+**Coverage:** 21/21 requirements mapped ✓
+
+---
+
+## Next Steps
+
+1. Execute Phase 1: `/gsd-execute-phase 1`
+2. Execute Phase 2: `/gsd-execute-phase 2`
+3. Execute Phase 3: `/gsd-execute-phase 3`
+4. Verify completion: `/gsd-verify-work`
+
+---
+
+_Last updated: 2026-02-19 after roadmap creation_