ai-devkit 0.3.2 → 0.4.0

package/web/app/vision/page.tsx

@@ -0,0 +1,49 @@
+import { getPage } from "@/lib/content/loader";
+import MarkdownContent from "@/components/MarkdownContent";
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Vision | AI DevKit",
+  description:
+    "The vision and purpose behind AI DevKit - bridging AI-assisted development with structured software engineering practices.",
+};
+
+export default function VisionPage() {
+  const page = getPage("vision");
+
+  if (!page) {
+    notFound();
+  }
+
+  return (
+    <div className="bg-white py-16">
+      <article className="mx-auto max-w-4xl px-4 sm:px-6 lg:px-8">
+        <MarkdownContent content={page.content} />
+      </article>
+      <div className="mt-16 pt-8 border-t border-gray-200 mx-auto max-w-4xl px-4 sm:px-6 lg:px-8">
+        <div className="bg-gray-50 p-8 rounded-lg border border-gray-200">
+          <h2 className="text-2xl font-bold mb-4">Ready to get started?</h2>
+          <p className="text-gray-600 mb-6">
+            See how AI DevKit can improve your development workflow with
+            structured practices and AI assistance.
+          </p>
+          <div className="flex flex-col sm:flex-row gap-4">
+            <a
+              href="/docs"
+              className="px-6 py-3 bg-black text-white rounded-lg font-medium hover:bg-gray-800 transition-colors no-underline text-center"
+            >
+              Get Started
+            </a>
+            <a
+              href="/roadmap"
+              className="px-6 py-3 border border-black rounded-lg font-medium hover:bg-gray-50 transition-colors no-underline text-center"
+            >
+              View Roadmap
+            </a>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/web/components/Footer.tsx

@@ -0,0 +1,81 @@
+export default function Footer() {
+  const currentYear = new Date().getFullYear();
+
+  return (
+    <footer className="border-t border-gray-200 mt-auto" role="contentinfo" aria-label="Site footer">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 py-8">
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-8">
+          <div>
+            <h3 className="text-sm font-bold mb-3">AI DevKit</h3>
+            <p className="text-sm text-gray-600 leading-relaxed">
+              A CLI toolkit for AI-assisted software development with phase templates and structured workflows.
+            </p>
+          </div>
+
+          <div>
+            <h3 className="text-sm font-bold mb-3">Resources</h3>
+            <ul className="space-y-2 text-sm">
+              <li>
+                <a href="/docs" className="text-gray-600 hover:text-black no-underline">
+                  Documentation
+                </a>
+              </li>
+              <li>
+                <a href="/vision" className="text-gray-600 hover:text-black no-underline">
+                  Vision
+                </a>
+              </li>
+              <li>
+                <a href="/roadmap" className="text-gray-600 hover:text-black no-underline">
+                  Roadmap
+                </a>
+              </li>
+              <li>
+                <a 
+                  href="https://github.com/codeaholicguy/ai-devkit" 
+                  target="_blank" 
+                  rel="noopener noreferrer"
+                  className="text-gray-600 hover:text-black no-underline"
+                >
+                  GitHub
+                </a>
+              </li>
+            </ul>
+          </div>
+
+          <div>
+            <h3 className="text-sm font-bold mb-3">Community</h3>
+            <ul className="space-y-2 text-sm">
+              <li>
+                <a 
+                  href="https://github.com/codeaholicguy/ai-devkit/issues" 
+                  target="_blank" 
+                  rel="noopener noreferrer"
+                  className="text-gray-600 hover:text-black no-underline"
+                >
+                  Issues
+                </a>
+              </li>
+              <li>
+                <a 
+                  href="https://github.com/codeaholicguy/ai-devkit/blob/main/CHANGELOG.md" 
+                  target="_blank" 
+                  rel="noopener noreferrer"
+                  className="text-gray-600 hover:text-black no-underline"
+                >
+                  Changelog
+                </a>
+              </li>
+            </ul>
+          </div>
+        </div>
+
+        <div className="mt-8 pt-8 border-t border-gray-200">
+          <p className="text-sm text-gray-500 text-center">
+            © {currentYear} AI DevKit. Released under the MIT License.
+          </p>
+        </div>
+      </div>
+    </footer>
+  );
+}

package/web/components/GitHubButton.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { useGitHubStars } from '@/lib/GitHubContext';
+import { formatStars } from '@/lib/utils';
+
+interface GitHubButtonProps {
+  repo: string;
+  className?: string;
+}
+
+export default function GitHubButton({ repo, className = '' }: GitHubButtonProps) {
+  const { stars, loading } = useGitHubStars();
+
+  return (
+    <a
+      href={`https://github.com/${repo}`}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={`inline-flex items-center gap-2 px-8 py-3 border border-black rounded-lg font-medium hover:bg-gray-50 transition-colors no-underline ${className}`}
+    >
+      <svg
+        className="w-5 h-5"
+        fill="currentColor"
+        viewBox="0 0 24 24"
+        aria-hidden="true"
+      >
+        <path
+          fillRule="evenodd"
+          d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"
+          clipRule="evenodd"
+        />
+      </svg>
+      <span>View on GitHub</span>
+      {!loading && stars !== null && (
+        <span className="flex items-center gap-1 px-2 py-0.5 bg-gray-100 rounded-full text-sm">
+          <svg
+            className="w-4 h-4 text-gray-700"
+            fill="currentColor"
+            viewBox="0 0 20 20"
+            aria-hidden="true"
+          >
+            <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z" />
+          </svg>
+          {formatStars(stars)}
+        </span>
+      )}
+    </a>
+  );
+}

package/web/components/GitHubStars.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { useGitHubStars } from '@/lib/GitHubContext';
+import { formatStars } from '@/lib/utils';
+
+export default function GitHubStars() {
+  const { stars } = useGitHubStars();
+
+  if (stars === null) {
+    return null;
+  }
+
+  return (
+    <span className="inline-flex items-center gap-1 text-xs text-gray-600">
+      <svg
+        className="w-3 h-3"
+        fill="currentColor"
+        viewBox="0 0 20 20"
+        aria-hidden="true"
+      >
+        <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z" />
+      </svg>
+      {formatStars(stars)}
+    </span>
+  );
+}
+

package/web/components/Header.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import Link from 'next/link';
+import { useState } from 'react';
+import GitHubStars from './GitHubStars';
+
+export default function Header() {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  const navigation = [
+    { name: 'Home', href: '/' },
+    { name: 'Documentation', href: '/docs' },
+    { name: 'Vision', href: '/vision' },
+    { name: 'Roadmap', href: '/roadmap' },
+  ];
+
+  return (
+    <header className="border-b border-gray-200">
+      <nav className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8" aria-label="Main navigation">
+        <div className="flex h-16 items-center justify-between">
+          <div className="flex items-center">
+            <Link href="/" className="text-xl font-bold no-underline hover:opacity-100">
+              AI DevKit
+            </Link>
+          </div>
+
+          <div className="hidden md:block">
+            <div className="flex items-center space-x-8">
+              {navigation.map((item) => (
+                <Link
+                  key={item.name}
+                  href={item.href}
+                  className="text-sm font-medium no-underline hover:opacity-70 transition-opacity"
+                >
+                  {item.name}
+                </Link>
+              ))}
+              <a
+                href="https://github.com/codeaholicguy/ai-devkit"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="inline-flex items-center gap-2 text-sm font-medium no-underline hover:opacity-70 transition-opacity"
+              >
+                <svg
+                  className="w-4 h-4"
+                  fill="currentColor"
+                  viewBox="0 0 24 24"
+                  aria-hidden="true"
+                >
+                  <path
+                    fillRule="evenodd"
+                    d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"
+                    clipRule="evenodd"
+                  />
+                </svg>
+                GitHub
+                <GitHubStars />
+              </a>
+            </div>
+          </div>
+
+          <div className="md:hidden">
+            <button
+              type="button"
+              onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+              className="inline-flex items-center justify-center p-2 rounded-md hover:bg-gray-100"
+              aria-expanded={mobileMenuOpen}
+            >
+              <span className="sr-only">Open main menu</span>
+              {mobileMenuOpen ? (
+                <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" strokeWidth="1.5" stroke="currentColor">
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                </svg>
+              ) : (
+                <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" strokeWidth="1.5" stroke="currentColor">
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" />
+                </svg>
+              )}
+            </button>
+          </div>
+        </div>
+
+        {mobileMenuOpen && (
+          <div className="md:hidden py-4 space-y-1 border-t border-gray-200">
+            {navigation.map((item) => (
+              <Link
+                key={item.name}
+                href={item.href}
+                className="block px-3 py-2 text-base font-medium no-underline hover:bg-gray-100 rounded-md"
+                onClick={() => setMobileMenuOpen(false)}
+              >
+                {item.name}
+              </Link>
+            ))}
+            <a
+              href="https://github.com/codeaholicguy/ai-devkit"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="block px-3 py-2 text-base font-medium no-underline hover:bg-gray-100 rounded-md"
+            >
+              GitHub
+            </a>
+          </div>
+        )}
+      </nav>
+    </header>
+  );
+}

package/web/components/MarkdownContent.tsx

@@ -0,0 +1,35 @@
+import { MDXRemote } from 'next-mdx-remote/rsc';
+import remarkGfm from 'remark-gfm';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeSlug from 'rehype-slug';
+
+interface MarkdownContentProps {
+  content: string;
+}
+
+export default async function MarkdownContent({ content }: MarkdownContentProps) {
+  return (
+    <div className="prose prose-lg max-w-none
+      prose-headings:font-bold 
+      prose-h1:text-4xl prose-h1:mb-6
+      prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4
+      prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3
+      prose-p:text-gray-700 prose-p:leading-relaxed
+      prose-a:text-black prose-a:underline hover:prose-a:opacity-70
+      prose-code:bg-gray-100 prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-code:text-sm
+      prose-pre:bg-gray-900 prose-pre:text-gray-100
+      prose-ul:my-6 prose-li:my-2
+      prose-strong:font-bold prose-strong:text-black">
+      <MDXRemote
+        source={content}
+        options={{
+          mdxOptions: {
+            remarkPlugins: [remarkGfm],
+            rehypePlugins: [rehypeHighlight, rehypeSlug],
+          },
+        }}
+      />
+    </div>
+  );
+}
+

package/web/components/SkipToContent.tsx

@@ -0,0 +1,11 @@
+export default function SkipToContent() {
+  return (
+    <a
+      href="#main-content"
+      className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-black focus:text-white focus:rounded-lg focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-black"
+    >
+      Skip to main content
+    </a>
+  );
+}
+

package/web/content/pages/vision.md

@@ -0,0 +1,42 @@
+---
+title: Vision
+description: The vision and purpose behind AI DevKit
+slug: vision
+order: 2
+---
+
+# Vision
+
+AI DevKit exists to bridge the gap between AI-assisted development and structured software engineering practices.
+
+## Our Purpose
+
+We believe that AI coding assistants are most powerful when they work within a well-defined engineering framework where documentation is clear, plans are systematic, and architecture is intentional.
+
+AI DevKit provides the scaffolding for that structure. It helps engineers reduce the back-and-forth of prompting, keep context in sync, and share memory between themselves and their AI tools.
+
+Our goal is simple:
+To make working with AI feel as natural and reliable as working with your favorite teammate, the one who already knows your project, your style, and your standards.
+
+## What We're Building
+
+A toolkit that enables developers to:
+
+- **Document thoroughly** - Capture requirements, design decisions, and implementation notes in a consistent format
+- **Plan systematically** - Break down complex features into manageable tasks with clear dependencies
+- **Collaborate effectively** - Share context with AI assistants and human teammates through well-organized documentation
+- **Maintain quality** - Ensure testing coverage and code review processes are baked into the workflow
+
+## Our Principles
+
+1. **Documentation-first development** - Start with clear requirements before writing code
+2. **Phase-based workflow** - Move through requirements, design, planning, implementation, and testing in a structured way
+3. **AI-friendly context** - Organize project knowledge so AI assistants can provide better assistance
+4. **Low friction** - Make it easy to follow best practices without heavy tooling overhead
+
+## Looking Forward
+
+We envision a future where structured development practices are the default, not the exception. Where every feature starts with clear requirements and ends with comprehensive tests. Where AI assistants amplify human capabilities by working within well-defined frameworks.
+
+AI DevKit is our contribution to that future.
+

package/web/content/roadmap/1-web.md

@@ -0,0 +1,9 @@
+---
+title: Public Website & Documentation
+status: completed
+priority: high
+order: 1
+---
+
+Launch a static website with landing page, comprehensive documentation, project vision, and development roadmap.
+

package/web/content/roadmap/2-integrations.md

@@ -0,0 +1,7 @@
+---
+title: Coding Agent Integration
+status: in-progress
+order: 2
+---
+
+Expand AI DevKit’s ecosystem with other AI coding agents such as: ChatGPT Codex, Gemini CLI, etc. The goal is to make AI DevKit the universal bridge between your favorite AI assistants and your development workflow, enabling smoother collaboration, faster iteration, and more consistent results.

package/web/content/roadmap/3-cli-enhancements.md

@@ -0,0 +1,8 @@
+---
+title: CLI Enhancements & Workflows
+status: planned
+order: 2
+---
+
+Expand CLI capabilities with interactive workflows, better error handling, and enhanced command chaining. Focus on improving developer experience and reducing friction in the structured development process.
+

package/web/content/roadmap/4-local-memory.md

@@ -0,0 +1,8 @@
+---
+title: Local Memory & Knowledge based
+status: planned
+order: 4
+---
+
+Build a local AI memory that learns from your coding habits, preferences, and team knowledge.
+This feature allows AI agents to access your skills, patterns, and project context directly from local, minimizing redundant prompts, speeding up workflows, and keeping your documents lightweight and focused.

package/web/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/web/lib/GitHubContext.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { createContext, useContext, useState, useEffect, ReactNode } from 'react';
+
+interface GitHubContextType {
+  stars: number | null;
+  loading: boolean;
+}
+
+const GitHubContext = createContext<GitHubContextType>({
+  stars: null,
+  loading: true,
+});
+
+export function GitHubProvider({ 
+  children, 
+  repo 
+}: { 
+  children: ReactNode; 
+  repo: string;
+}) {
+  const [stars, setStars] = useState<number | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function fetchStars() {
+      try {
+        const response = await fetch(`https://api.github.com/repos/${repo}`);
+        if (response.ok) {
+          const data = await response.json();
+          setStars(data.stargazers_count);
+        }
+      } catch (error) {
+        console.error('Failed to fetch GitHub stars:', error);
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchStars();
+  }, [repo]);
+
+  return (
+    <GitHubContext.Provider value={{ stars, loading }}>
+      {children}
+    </GitHubContext.Provider>
+  );
+}
+
+export function useGitHubStars() {
+  const context = useContext(GitHubContext);
+  if (!context) {
+    throw new Error('useGitHubStars must be used within a GitHubProvider');
+  }
+  return context;
+}
+

package/web/lib/content/loader.ts

@@ -0,0 +1,152 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { Page, PageMetadata, RoadmapItem, RoadmapItemMetadata } from './types';
+
+const contentDirectory = path.join(process.cwd(), 'content');
+const docsDirectory = path.join(contentDirectory, 'docs');
+const pagesDirectory = path.join(contentDirectory, 'pages');
+
+/**
+ * Get all Markdown files from a directory
+ */
+function getMarkdownFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  
+  const files = fs.readdirSync(dir);
+  return files
+    .filter(file => file.endsWith('.md') || file.endsWith('.mdx'))
+    .map(file => path.join(dir, file));
+}
+
+/**
+ * Parse a Markdown file with frontmatter
+ */
+function parseMarkdownFile<T>(filePath: string): { metadata: T; content: string } {
+  const fileContents = fs.readFileSync(filePath, 'utf8');
+  const { data, content } = matter(fileContents);
+  
+  return {
+    metadata: data as T,
+    content: content.trim(),
+  };
+}
+
+/**
+ * Get a single page by slug
+ */
+export function getPage(slug: string): Page | null {
+  const filePath = path.join(pagesDirectory, `${slug}.md`);
+  
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  
+  const parsed = parseMarkdownFile<PageMetadata>(filePath);
+  
+  return {
+    metadata: {
+      ...parsed.metadata,
+      slug,
+    },
+    content: parsed.content,
+  };
+}
+
+/**
+ * Get all pages
+ */
+export function getAllPages(): Page[] {
+  const files = getMarkdownFiles(pagesDirectory);
+  
+  const pages = files.map(filePath => {
+    const slug = path.basename(filePath, path.extname(filePath));
+    const parsed = parseMarkdownFile<PageMetadata>(filePath);
+    
+    return {
+      metadata: {
+        ...parsed.metadata,
+        slug,
+      },
+      content: parsed.content,
+    };
+  });
+  
+  // Sort by order if specified
+  return pages.sort((a, b) => {
+    const orderA = a.metadata.order ?? 999;
+    const orderB = b.metadata.order ?? 999;
+    return orderA - orderB;
+  });
+}
+
+/**
+ * Get a single documentation page by slug
+ */
+export function getDocPage(slug: string): Page | null {
+  const filePath = path.join(docsDirectory, `${slug}.md`);
+  
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  
+  const parsed = parseMarkdownFile<PageMetadata>(filePath);
+  
+  return {
+    metadata: {
+      ...parsed.metadata,
+      slug,
+    },
+    content: parsed.content,
+  };
+}
+
+/**
+ * Get all documentation pages
+ */
+export function getAllDocPages(): Page[] {
+  const files = getMarkdownFiles(docsDirectory);
+  
+  const pages = files.map(filePath => {
+    const slug = path.basename(filePath, path.extname(filePath));
+    const parsed = parseMarkdownFile<PageMetadata>(filePath);
+    
+    return {
+      metadata: {
+        ...parsed.metadata,
+        slug,
+      },
+      content: parsed.content,
+    };
+  });
+  
+  // Sort by order if specified
+  return pages.sort((a, b) => {
+    const orderA = a.metadata.order ?? 999;
+    const orderB = b.metadata.order ?? 999;
+    return orderA - orderB;
+  });
+}
+
+/**
+ * Get all roadmap items
+ */
+export function getRoadmap(): RoadmapItem[] {
+  const roadmapDir = path.join(contentDirectory, 'roadmap');
+  const files = getMarkdownFiles(roadmapDir);
+  
+  const items = files.map(filePath => {
+    const parsed = parseMarkdownFile<RoadmapItemMetadata>(filePath);
+    return parsed as RoadmapItem;
+  });
+  
+  // Sort by order if specified, then by priority
+  return items.sort((a, b) => {
+    const orderA = a.metadata.order ?? 999;
+    const orderB = b.metadata.order ?? 999;
+    return orderA - orderB;
+  });
+}
+