Plan mermaid diagrams feature implementation

[jschulte]

No description provided.

[Copilot]

Pull Request Overview

This PR introduces comprehensive planning documentation for implementing automatic Mermaid diagram generation for StackShift documentation. The feature aims to visualize the workflow state machine, system architecture, class structures, and sequence diagrams to improve developer onboarding and code comprehension.

Key Changes

• Complete feature specification with functional and non-functional requirements
• Implementation plan with research findings and technology decisions
• Detailed task breakdown with 69 tasks organized by user story
• Data model definitions and TypeScript API contracts
• Quickstart implementation guide with code examples

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
spec.md	Feature specification defining requirements, acceptance criteria, and success metrics for Mermaid diagram generation
impl-plan.md	Implementation plan with technical context, architecture approach, and constitutional alignment check
research.md	Research findings on TypeScript AST parsing, Mermaid best practices, CI/CD integration, and testing strategies
tasks.md	Comprehensive task list with 69 tasks organized into 8 phases covering setup, user stories, and polish
quickstart.md	Step-by-step implementation guide with code examples for generators, parsers, and embedders
data-model.md	Data structure definitions for AST nodes, diagram models, and Mermaid output formats
contracts/types.ts	TypeScript type definitions for gear states, AST nodes, diagram models, and Mermaid code
contracts/diagram-generator.contract.ts	API contracts for diagram generation interfaces and error handling
contracts/ast-parser.contract.ts	API contracts for TypeScript AST parsing and relationship extraction
contracts/embedder.contract.ts	API contracts for embedding diagrams in documentation files
contracts/README.md	Overview of contract files and their usage patterns
agent-context.md	Technology reference documenting patterns, practices, and anti-patterns for future AI agents

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The task counts are inconsistent across the document. Line 26 states "Total Tasks: 35" but line 457 states "Total Tasks: 69". The breakdown on line 459 shows "39 tasks" for MVP, "24 tasks" for P1, and "9 tasks" for Polish, which totals 72, not 69.

Please verify and correct the task counts to ensure accurate project estimation.

[Copilot]

This line incorrectly references @typescript/compiler as a "NEEDS CLARIFICATION" item. The package should be typescript, not @typescript/compiler. This incorrect package name appears to be carried over from earlier in the document and should be corrected to avoid confusion.

Suggested change

	- **@typescript/compiler**: NEEDS CLARIFICATION - version, size, maintenance status?
	- **typescript**: NEEDS CLARIFICATION - version, size, maintenance status?

[Copilot]

The question asks about using @typescript/compiler package versus typescript package. However, @typescript/compiler is not a valid package name. This entire section should reference the correct package name typescript to avoid confusion during research and implementation.

Suggested change

	**Question:** Should we use `@typescript/compiler` package or `typescript` package directly?
	**Impact:** HIGH - affects dependency size, API availability
	**Options:**
	- Option A: Use full `typescript` package (includes compiler API, 32MB)
	- Option B: Use lightweight wrapper if available
	**Question:** Should we use the `typescript` package directly, or look for a lightweight wrapper/alternative?
	**Impact:** HIGH - affects dependency size, API availability
	**Options:**
	- Option A: Use full `typescript` package (includes compiler API, ~32MB)
	- Option B: Use a lightweight wrapper or alternative if available

[Copilot]

In the WorkflowDiagramGenerator class, the parse method returns a WorkflowDiagram but the imports reference the types from a relative path that assumes the contracts are in a specific location: '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types'.

This import path will not work when the actual implementation is in scripts/generate-diagrams/generators/workflow-diagram.ts because the contracts directory is in the spec folder, not in the implementation location. The types should either be:

1. Copied to the implementation directory structure
2. Imported from a shared types file in the implementation
3. The import path needs to be corrected for the actual file structure

Suggested change

	import type { WorkflowDiagram, MermaidCode, GearState } from '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types';
	import type { WorkflowDiagram, MermaidCode, GearState } from '../../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types';

[Copilot]

Same import path issue as in previous code examples. The path '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types' will not work when implemented in the actual file structure.

Suggested change

	import type { ClassNode, InterfaceNode, MethodNode, PropertyNode } from '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types';
	// Update the import below to match your project's alias or path mapping.
	// For example, configure `@contracts/types` in your tsconfig.json to point to the correct location.
	import type { ClassNode, InterfaceNode, MethodNode, PropertyNode } from '@contracts/types';

[Copilot]

The same import path issue exists here. The path '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types' assumes the implementation file is in a specific location relative to the specs directory, but this won't work when the code is actually implemented in scripts/generate-diagrams/generators/architecture-diagram.ts.

Suggested change

	import type { ArchitectureDiagram, MermaidCode } from '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types';
	// Make sure to configure the path alias '@contracts/types' in your tsconfig.json
	import type { ArchitectureDiagram, MermaidCode } from '@contracts/types';

[Copilot]

Same import path issue. The path '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types' needs to be corrected for the actual implementation structure.

Suggested change

	import type { ClassDiagram, MermaidCode } from '../../../production-readiness-specs/F005-mermaid-diagrams/contracts/types';
	// TODO: Update the import path below to match your project structure
	import type { ClassDiagram, MermaidCode } from '@contracts/types';

[Copilot]

The acceptance criteria states "Shows all 7 states" which is correct, but the list includes only 7 gear names. However, this is inconsistent with the term "6-gear process" used elsewhere in the document. Additionally, the state names use different formats: "reverse-engineer" (with hyphen) in the list but likely "reverse_engineer" (with underscore) in the actual state file based on line 62 of impl-plan.md.

Please ensure consistent naming convention is documented - whether states use hyphens or underscores.

Suggested change

	- ✅ Shows all 7 states (analyze, reverse-engineer, create-specs, gap-analysis, complete-spec, implement, cruise-control)
	- ✅ Shows valid state transitions
	- ✅ Auto-generated from .stackshift-state.json
	- ✅ Outputs to docs/diagrams/workflow.mmd
	- ✅ Shows all 7 states (analyze, reverse_engineer, create_specs, gap_analysis, complete_spec, implement, cruise_control)
	- ✅ Shows valid state transitions
	- ✅ Auto-generated from .stackshift-state.json
	- ✅ Outputs to docs/diagrams/workflow.mmd
	**Naming Convention Note:** All state names use snake_case (underscores), matching the keys in .stackshift-state.json (e.g., `reverse_engineer`, not `reverse-engineer`).
	**Clarification:** The process is sometimes referred to as a "6-gear process", but there are 7 workflow states in total.

[Copilot]

Inconsistent state naming: The states listed here use hyphens (e.g., "reverse-engineer", "create-specs"), but based on the code examples elsewhere and the note about snake_case convention in agent-context.md (line 262), the actual implementation should use underscores (e.g., "reverse_engineer", "create_specs").

The acceptance criteria should reflect the actual naming convention that will be used in the code.

Suggested change

	- Shows all 7 states (analyze, reverse-engineer, create-specs, gap-analysis, complete-spec, implement, cruise-control)
	- Shows all 7 states (analyze, reverse_engineer, create_specs, gap_analysis, complete_spec, implement, cruise_control)