ai-devkit 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-devkit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A CLI toolkit for AI-assisted software development with phase templates and environment setup",
   "main": "dist/index.js",
   "bin": {
@@ -10,6 +10,9 @@
     "build": "tsc",
     "dev": "ts-node src/cli.ts",
     "lint": "eslint src --ext .ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -23,24 +26,26 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "chalk": "^4.1.2",
     "commander": "^11.1.0",
-    "inquirer": "^8.2.6",
     "fs-extra": "^11.2.0",
-    "yaml": "^2.3.4",
-    "chalk": "^4.1.2"
+    "inquirer": "^8.2.6",
+    "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@types/node": "^20.11.5",
-    "@types/inquirer": "^8.2.10",
     "@types/fs-extra": "^11.0.4",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.3.3",
-    "eslint": "^8.56.0",
+    "@types/inquirer": "^8.2.10",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.11.5",
     "@typescript-eslint/eslint-plugin": "^6.19.1",
-    "@typescript-eslint/parser": "^6.19.1"
+    "@typescript-eslint/parser": "^6.19.1",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
   },
   "engines": {
     "node": ">=16.0.0"
   }
 }
-

package/templates/commands/capture-knowledge.md

@@ -0,0 +1,46 @@
+# Knowledge Capture Assistant
+
+Guide me through creating a structured understanding of a code entry point and saving it to the knowledge docs.
+
+## Step 1: Gather Context
+- Entry point (file, folder, function, API)
+- Why this entry point matters (feature, bug, investigation)
+- Relevant requirements/design docs (if any)
+- Desired depth or focus areas (logic, dependencies, data flow)
+
+## Step 2: Validate Entry Point
+- Determine entry point type and confirm it exists
+- Surface ambiguity (multiple matches) and ask for clarification
+- If not found, suggest likely alternatives or spelling fixes
+
+## Step 3: Collect Source Context
+- Read the primary file/module and summarize purpose, exports, key patterns
+- For folders: list structure, highlight key modules
+- For functions/APIs: capture signature, parameters, return values, error handling
+- Extract essential snippets (avoid large dumps)
+
+## Step 4: Analyze Dependencies
+- Build a dependency view up to depth 3
+- Track visited nodes to avoid loops
+- Categorize dependencies (imports, function calls, services, external packages)
+- Note important external systems or generated code that should be excluded
+
+## Step 5: Synthesize Explanation
+- Draft an overview (purpose, language, high-level behavior)
+- Detail core logic, key components, execution flow, patterns
+- Highlight error handling, performance, security considerations
+- Identify potential improvements or risks discovered during analysis
+
+## Step 6: Create Documentation
+- Normalize entry point name to kebab-case (`calculateTotalPrice` → `calculate-total-price`)
+- Create `docs/ai/implementation/knowledge-{name}.md` using the headings implied in Step 5 (Overview, Implementation Details, Dependencies, Visual Diagrams, Additional Insights, Metadata, Next Steps)
+- Populate sections with findings, diagrams, and metadata (analysis date, depth, files touched)
+- Include mermaid diagrams when they clarify flows or relationships
+
+## Step 7: Review & Next Actions
+- Summarize key insights and open questions for follow-up
+- Suggest related areas for deeper dives or refactors
+- Confirm the knowledge file path and remind to commit it
+- Encourage running `/capture-knowledge` again for related entry points if needed
+
+Let me know the entry point and goals when you’re ready to begin the knowledge capture.

package/templates/commands/debug.md

@@ -0,0 +1,45 @@
+# Local Debugging Assistant
+
+Help me debug an issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code.
+
+## Step 1: Gather Context
+Ask me for:
+- Brief issue description (what is happening?)
+- Expected behavior or acceptance criteria (what should happen?)
+- Current behavior and any error messages/logs
+- Recent related changes or deployments
+- Scope of impact (users, services, environments)
+
+## Step 2: Clarify Reality vs Expectation
+- Restate the observed behavior vs the expected outcome
+- Confirm relevant requirements, tickets, or docs that define the expectation
+- Identify acceptance criteria for the fix (how we know it is resolved)
+
+## Step 3: Reproduce & Isolate
+- Determine reproducibility (always, intermittent, environment-specific)
+- Capture reproduction steps or commands
+- Note any available tests that expose the failure
+- List suspected components, services, or modules
+
+## Step 4: Analyze Potential Causes
+- Brainstorm plausible root causes (data, config, code regressions, external dependencies)
+- Gather supporting evidence (logs, metrics, traces, screenshots)
+- Highlight gaps or unknowns that need investigation
+
+## Step 5: Surface Options
+- Present possible resolution paths (quick fix, deeper refactor, rollback, feature flag, etc.)
+- For each option, list pros/cons, risks, and verification steps
+- Consider required approvals or coordination
+
+## Step 6: Confirm Path Forward
+- Ask which option we should pursue
+- Summarize chosen approach, required pre-work, and success criteria
+- Plan validation steps (tests, monitoring, user sign-off)
+
+## Step 7: Next Actions & Tracking
+- Document tasks, owners, and timelines for the selected option
+- Note follow-up actions after deployment (monitoring, comms, postmortem if needed)
+- Encourage updating relevant docs/tests once resolved
+
+Let me know when you're ready to walk through the debugging flow.
+

package/templates/{env/cursor/commands → commands}/new-requirement.md

@@ -106,7 +106,7 @@ Provide the MR/PR description:
 ### Testing
 - Unit tests: [coverage/status]
 - Integration tests: [status]
-- Manual testing: ✓ Completed
+- Manual testing: Completed
 - Test documentation: `docs/ai/testing/feature-{name}.md`
 
 ### Checklist

package/web/.nojekyll

@@ -0,0 +1,2 @@
+# This file tells GitHub Pages not to process the site with Jekyll
+

package/web/CNAME

@@ -0,0 +1 @@
+ai-devkit.com

package/web/README.md

@@ -0,0 +1,100 @@
+# AI DevKit Website
+
+This is the source code for the AI DevKit static website built with Next.js.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the site.
+
+## Building
+
+```bash
+npm run build
+```
+
+This generates static files in the `out/` directory.
+
+## Deployment
+
+The site is automatically deployed to GitHub Pages when changes are pushed to the `main` branch.
+
+### Manual Deployment Setup
+
+1. Go to your repository settings on GitHub
+2. Navigate to **Settings > Pages**
+3. Under **Source**, select **GitHub Actions**
+4. The workflow will run automatically on push to main
+
+## Project Structure
+
+```
+web/
+├── app/              # Next.js app directory
+│   ├── docs/         # Documentation pages
+│   ├── roadmap/      # Roadmap page
+│   ├── vision/       # Vision page
+│   ├── layout.tsx    # Root layout
+│   └── page.tsx      # Landing page
+├── components/       # Reusable components
+├── content/          # Markdown content
+│   ├── docs/         # Documentation files
+│   ├── pages/        # Static pages
+│   └── roadmap/      # Roadmap items
+├── lib/              # Utilities and helpers
+│   └── content/      # Content loading utilities
+└── public/           # Static assets
+```
+
+## Content Management
+
+All content is managed via Markdown files with frontmatter:
+
+- Documentation: `content/docs/*.md`
+- Pages (vision, etc): `content/pages/*.md`
+- Roadmap items: `content/roadmap/*.md`
+
+### Adding New Documentation
+
+Create a new file in `content/docs/`:
+
+```markdown
+---
+title: Your Doc Title
+description: Brief description
+slug: your-doc-slug
+order: 1
+---
+
+# Your content here...
+```
+
+### Adding Roadmap Items
+
+Create a new file in `content/roadmap/`:
+
+```markdown
+---
+title: Feature Name
+status: planned | in-progress | completed | on-hold
+timeframe: Q1 2026
+priority: high | medium | low
+order: 1
+---
+
+Feature description...
+```
+
+## SEO
+
+The site includes:
+
+- Comprehensive metadata
+- Sitemap at `/sitemap.xml`
+- Robots.txt at `/robots.txt`
+- Open Graph tags for social sharing
+- Semantic HTML and ARIA labels

package/web/app/globals.css

@@ -0,0 +1,122 @@
+@import "tailwindcss";
+
+@theme {
+  --color-white: #ffffff;
+  --color-black: #000000;
+  --color-gray-50: #fafafa;
+  --color-gray-100: #f5f5f5;
+  --color-gray-200: #e5e5e5;
+  --color-gray-300: #d4d4d4;
+  --color-gray-400: #a3a3a3;
+  --color-gray-500: #737373;
+  --color-gray-600: #525252;
+  --color-gray-700: #404040;
+  --color-gray-800: #262626;
+  --color-gray-900: #171717;
+  --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+  --font-mono: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;
+}
+
+body {
+  background: #ffffff;
+  color: #000000;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-weight: 700;
+  line-height: 1.2;
+  margin-bottom: 0.5em;
+}
+
+h1 { font-size: 2.5rem; }
+h2 { font-size: 2rem; }
+h3 { font-size: 1.75rem; }
+h4 { font-size: 1.5rem; }
+h5 { font-size: 1.25rem; }
+h6 { font-size: 1rem; }
+
+p {
+  line-height: 1.6;
+  margin-bottom: 1em;
+}
+
+a {
+  transition: opacity 0.2s;
+}
+
+a:hover {
+  opacity: 0.7;
+}
+
+code {
+  background: #f5f5f5;
+  color: #000000;
+  padding: 0.2em 0.4em;
+  border-radius: 3px;
+  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;
+  font-size: 0.9em;
+}
+
+pre code {
+  background: transparent;
+  padding: 0;
+  color: inherit;
+}
+
+pre {
+  padding: 1rem;
+  border-radius: 0.5rem;
+  overflow-x: auto;
+  margin: 1.5rem 0;
+}
+
+article pre {
+  background: #000000;
+  color: #ffffff;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+.focus\:not-sr-only:focus {
+  position: static;
+  width: auto;
+  height: auto;
+  padding: inherit;
+  margin: inherit;
+  overflow: visible;
+  clip: auto;
+  white-space: normal;
+}
+
+*:focus-visible {
+  outline: 2px solid #000000;
+  outline-offset: 2px;
+}
+
+h1, h2, h3, h4, h5, h6, p, span, div {
+  color: inherit;
+}
+
+article ul, article ol {
+  list-style-type: unset;
+  padding-left: 1em;
+  margin-bottom: 1em;
+}
+
+article a {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}

package/web/app/layout.tsx

@@ -0,0 +1,106 @@
+import type { Metadata } from "next";
+import "./globals.css";
+import Header from "@/components/Header";
+import Footer from "@/components/Footer";
+import SkipToContent from "@/components/SkipToContent";
+import { GitHubProvider } from "@/lib/GitHubContext";
+import Script from "next/script";
+
+const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "https://ai-devkit.com";
+
+export const metadata: Metadata = {
+  metadataBase: new URL(siteUrl),
+  title: {
+    default: "AI DevKit - Structured AI-Assisted Development",
+    template: "%s | AI DevKit",
+  },
+  description:
+    "A CLI toolkit for AI-assisted software development with phase templates and structured workflows. Improve your development process with requirements, design, planning, and testing documentation.",
+  keywords: [
+    "AI",
+    "development",
+    "CLI",
+    "templates",
+    "documentation",
+    "structured development",
+    "AI-assisted coding",
+    "software engineering",
+    "project management",
+    "development workflow",
+    "specs driven development",
+  ],
+  authors: [{ name: "AI DevKit Team" }],
+  creator: "AI DevKit",
+  publisher: "AI DevKit",
+  openGraph: {
+    title: "AI DevKit - Structured AI-Assisted Development",
+    description:
+      "A CLI toolkit for AI-assisted software development with phase templates and structured workflows.",
+    url: siteUrl,
+    siteName: "AI DevKit",
+    locale: "en_US",
+    type: "website",
+  },
+  twitter: {
+    card: "summary_large_image",
+    title: "AI DevKit - Structured AI-Assisted Development",
+    description:
+      "A CLI toolkit for AI-assisted software development with phase templates and structured workflows.",
+  },
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      "max-video-preview": -1,
+      "max-image-preview": "large",
+      "max-snippet": -1,
+    },
+  },
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body className="flex flex-col min-h-screen">
+        <Script
+          async
+          src="https://www.googletagmanager.com/gtag/js?id=G-XYJ8T5JK0Y"
+        ></Script>
+        <Script>
+          {`
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', 'G-XYJ8T5JK0Y');
+          `}
+        </Script>
+        <GitHubProvider repo="codeaholicguy/ai-devkit">
+          <SkipToContent />
+          <Header />
+          <main id="main-content" className="flex-1">
+            {children}
+          </main>
+          <Footer />
+          <Script
+            id="structured-data"
+            type="application/ld+json"
+            dangerouslySetInnerHTML={{
+              __html: JSON.stringify({
+                "@context": "https://schema.org",
+                "@type": "website",
+                name: "AI DevKit",
+                url: siteUrl,
+              }),
+            }}
+          />
+        </GitHubProvider>
+      </body>
+    </html>
+  );
+}

package/web/app/page.tsx

@@ -0,0 +1,119 @@
+import Link from "next/link";
+import GitHubButton from "@/components/GitHubButton";
+
+export default function Home() {
+  return (
+    <div className="bg-white">
+      <section className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 py-20 md:py-32">
+        <div className="text-center">
+          <h1 className="text-4xl md:text-6xl font-bold mb-6">
+            Structured AI-Assisted
+            <br />
+            Development
+          </h1>
+          <p className="text-xl md:text-2xl text-gray-600 mb-8 max-w-3xl mx-auto">
+            A CLI toolkit that brings structure to AI-assisted software development with phase templates, 
+            systematic planning, and comprehensive documentation workflows.
+          </p>
+          <div className="flex flex-col sm:flex-row gap-4 justify-center items-center">
+            <Link 
+              href="/docs" 
+              className="px-8 py-3 bg-black text-white rounded-lg font-medium hover:bg-gray-800 transition-colors no-underline"
+            >
+              Get Started
+            </Link>
+            <GitHubButton repo="codeaholicguy/ai-devkit" />
+          </div>
+        </div>
+      </section>
+
+      <section className="bg-gray-50 py-20">
+        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+          <h2 className="text-3xl md:text-4xl font-bold text-center mb-12">
+            Why AI DevKit?
+          </h2>
+          <div className="grid md:grid-cols-3 gap-8">
+            <div className="bg-white p-8 rounded-lg border border-gray-200">
+              <h3 className="text-xl font-bold mb-3">Documentation-First</h3>
+              <p className="text-gray-600 leading-relaxed">
+                Start with clear requirements, design decisions, and implementation plans. 
+                Keep your project knowledge organized and accessible.
+              </p>
+            </div>
+            <div className="bg-white p-8 rounded-lg border border-gray-200">
+              <h3 className="text-xl font-bold mb-3">Phase-Based Workflow</h3>
+              <p className="text-gray-600 leading-relaxed">
+                Move systematically through requirements, design, planning, implementation, 
+                and testing. No step gets skipped.
+              </p>
+            </div>
+            <div className="bg-white p-8 rounded-lg border border-gray-200">
+              <h3 className="text-xl font-bold mb-3">AI-Friendly Context</h3>
+              <p className="text-gray-600 leading-relaxed">
+                Organize project knowledge so AI assistants provide better guidance. 
+                Amplify human capabilities with structured context.
+              </p>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section className="py-20">
+        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+          <div className="max-w-3xl mx-auto">
+            <h2 className="text-3xl md:text-4xl font-bold mb-8 text-center">
+              Quick Start
+            </h2>
+            <div className="bg-gray-50 p-8 rounded-lg border border-gray-200">
+              <p className="text-gray-600 mb-4">Install AI DevKit globally:</p>
+              <pre className="bg-black text-white p-4 rounded overflow-x-auto">
+                <code>npm install -g ai-devkit</code>
+              </pre>
+              <p className="text-gray-600 mt-6 mb-4">Initialize in your project:</p>
+              <pre className="bg-black text-white p-4 rounded overflow-x-auto">
+                <code>ai-devkit init</code>
+              </pre>
+              <p className="text-gray-600 mt-6">or</p>
+              <pre className="bg-black text-white p-4 rounded overflow-x-auto">
+                <code>npx ai-devkit init</code>
+              </pre>
+              <p className="text-gray-600 mt-6">
+                This creates a <code>docs/ai/</code> directory with phase templates for 
+                requirements, design, planning, implementation, testing, deployment, and monitoring.
+              </p>
+              <p className="text-gray-600 mt-6">
+                In Cursor or Claude Code, type <code>/new-requirement</code> to get started.
+              </p>
+              <iframe src="https://www.youtube.com/embed/8cNFkHEVE3o?autoplay=1&mute=1&loop=1&controls=0" className="w-full h-[440px]" />
+            </div>
+            <div className="text-center mt-8">
+              <Link 
+                href="/docs" 
+                className="text-lg font-medium hover:opacity-70 transition-opacity"
+              >
+                Read the full documentation →
+              </Link>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section className="bg-black text-white py-20">
+        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 text-center">
+          <h2 className="text-3xl md:text-4xl font-bold mb-6">
+            Ready to structure your development?
+          </h2>
+          <p className="text-xl text-gray-300 mb-8 max-w-2xl mx-auto">
+            Join developers who are building better software with AI assistance and structured workflows.
+          </p>
+          <Link 
+            href="/docs" 
+            className="inline-block px-8 py-3 bg-white text-black rounded-lg font-medium hover:bg-gray-100 transition-colors no-underline"
+          >
+            Get Started Now
+          </Link>
+        </div>
+      </section>
+    </div>
+  );
+}